QWebEnginePage Class

This enum describes the platform feature access categories that the user may be asked to grant or deny access to:

See Also▲

This enum indicates whether the implementation of the chooseFiles() function should return only one file or may return multiple files:

See Also▲

flags QWebEnginePage::FindFlags

This enum describes the options available to the findText() function. The options can be OR-ed together from the following list:

The FindFlags type is a typedef for QFlags<FindFlag>. It stores an OR combination of FindFlag values.

This enum describes the different severity levels a JavaScript console message can have:

This enum describes the lifecycle state of the page:

This enum was introduced or modified in Qt 5.14.

See Also▲

This enum describes the type of a navigation request:

See Also▲

This enum describes the permission policies that the user may set for data or device access:

See Also▲

This enum describes the status with which the render process terminated:

This enum was introduced or modified in Qt 5.6.

This enum describes the types of action which can be performed on the web page.

Actions only have an effect when they are applicable.

The availability of actions can be be determined by checking isEnabled() on the action returned by action().

This enum describes the types of window that can be created by the createWindow() function:

This property holds whether the current page audio is muted.

The default value is false.

This property was introduced in Qt 5.7.

Access functions:

• bool isAudioMuted() const

• void setAudioMuted(bool muted)

Notifier signal:

• void audioMutedChanged(bool muted)

See Also▲

This property holds the page's background color behind the document's body.

You can set the background color to Qt::transparent or to a translucent color to see through the document, or you can set it to match your web content in a hybrid application to prevent the white flashes that may appear during loading.

The default value is white.

This property was introduced in Qt 5.6.

Access functions:

• backgroundColor() const

• void setBackgroundColor(const &color)

This property holds the size of the page contents.

This property was introduced in Qt 5.7.

Access functions:

• contentsSize() const

Notifier signal:

• void contentsSizeChanged(const &size)

This property holds whether this page contains selected content or not.

Access functions:

• bool hasSelection() const

See Also▲

This property holds the icon associated with the page currently viewed.

By default, this property contains a null icon. If touch icons are disabled (see QWebEngineSettings::TouchIconsEnabled), the favicon is provided in two sizes (16x16 and 32x32 pixels) encapsulated in QIcon. Otherwise, single icon is provided with the largest available size.

This property was introduced in Qt 5.7.

Access functions:

• icon() const

Notifier signal:

• void iconChanged(const &icon)

See Also▲

This property holds the URL of the icon associated with the page currently viewed.

By default, this property contains an empty URL.

Access functions:

• iconUrl() const

Notifier signal:

• void iconUrlChanged(const &url)

See Also▲

This property holds the current lifecycle state of the page.

The following restrictions are enforced by the setter:

• A visible page must remain in the Active state.

• If the page is being inspected by a devToolsPage then both pages must remain in the Active states.

• A page in the Discarded state can only transition to the Active state. This will cause a reload of the page.

These are the only hard limits on the lifecycle state, but see also recommendedState for the recommended soft limits.

This property was introduced in Qt 5.14.

Access functions:

• lifecycleState() const

• void setLifecycleState( state)

Notifier signal:

• void lifecycleStateChanged( state)

See Also▲

This property holds whether the page is currently loading.

This property was introduced in Qt 6.2.

Access functions:

• bool isLoading() const

Notifier signal:

• void loadingChanged(const &loadingInfo)

See Also▲

This property holds the current page's audible state, that is, whether audio was recently played or not.

The default value is false.

This property was introduced in Qt 5.7.

Access functions:

• bool recentlyAudible() const

Notifier signal:

• void recentlyAudibleChanged(bool recentlyAudible)

See Also▲

This property holds the recommended limit for the lifecycle state of the page.

Setting the lifecycle state to a lower resource usage state than the recommended state may cause side-effects such as stopping background audio playback or loss of HTML form input. Setting the lifecycle state to a higher resource state is however completely safe.

This property was introduced in Qt 5.14.

Access functions:

• recommendedState() const

Notifier signal:

• void recommendedStateChanged( state)

See Also▲

This property holds the process ID (PID) of the render process assigned to the current page's main frame.

If no render process is available yet, 0 is returned.

This property was introduced in Qt 5.15.

Access functions:

• qint64 renderProcessPid() const

Notifier signal:

• void renderProcessPidChanged(qint64 pid)

This property holds the URL that was originally requested to be loaded by the page that is currently viewed.

Access functions:

• requestedUrl() const

See Also▲

This property holds the scroll position of the page contents.

This property was introduced in Qt 5.7.

Access functions:

• scrollPosition() const

Notifier signal:

• void scrollPositionChanged(const &position)

This property holds the text currently selected.

By default, this property contains an empty string.

Access functions:

• selectedText() const

See Also▲

This property holds the title of the page as defined by the HTML <title> element.

If the page has no <title> element, then the URL is used instead. For file:// URLs only the filename is used and not the full path.

By default, before any content has been loaded, this property contains an empty string.

Access functions:

• title() const

See Also▲

This property holds the URL of the page currently viewed.

Setting this property clears the view and loads the URL.

By default, this property contains an empty, invalid URL.

Access functions:

• url() const

• void setUrl(const &url)

See Also▲

This property holds whether the page is considered visible in the Page Visibility API.

Setting this property changes the Document.hidden and the Document.visibilityState properties in JavaScript which web sites can use to voluntarily reduce their resource usage if they are not visible to the user.

If the page is connected to a view then this property will be managed automatically by the view according to it's own visibility.

This property was introduced in Qt 5.14.

Access functions:

• bool isVisible() const

• void setVisible(bool visible)

Notifier signal:

• void visibleChanged(bool visible)

See Also▲

This property holds the zoom factor for the page content.

Valid values are within the range from 0.25 to 5.0. The default factor is 1.0.

Access functions:

• qreal zoomFactor() const

• void setZoomFactor(qreal factor)

[since 5.7] void QWebEnginePage::runJavaScript(const QString &scriptSource, quint32 worldId = 0, const std::function<void (const QVariant &)> &resultCallback = {})

Runs the JavaScript code contained in scriptSource without checking whether the DOM of the page has been constructed. If you need more control over how the script is run, consider using scripts() instead.

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, resultCallback is called with the result of the last executed statement. resultCallback 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.

This function was introduced in Qt 5.7.

See Also▲

Constructs an empty QWebEnginePage with the parent parent.

Constructs an empty web engine page in the web engine profile profile with the parent parent.

If the profile is not the default profile, the caller must ensure that the profile stays alive for as long as the page does.

This function was introduced in Qt 5.5.

Destroys the web page.

This function is called upon receiving a request to navigate to the specified url by means of the specified navigation type type. isMainFrame indicates whether the request corresponds to the main frame or a child frame. If the function returns true, the navigation request is accepted and url is loaded. The default implementation accepts all navigation requests.

Navigation requests can be delegated to the Qt application instead of having the HTML handler engine process them by overloading this function. This is necessary when an HTML document is used as part of the user interface, and not to display external data, for example, when displaying a list of results.

The QWebEngineUrlRequestInterceptor class offers further options for intercepting and manipulating requests.

This function was introduced in Qt 5.5.

Returns a QAction for the specified WebAction action.

The action is owned by the QWebEnginePage but you can customize the look by changing its properties.

QWebEnginePage also takes care of implementing the action, so that upon triggering the corresponding action is performed on the page.

See Also▲

This signal is emitted when the page's muted state changes.

This function was introduced in Qt 5.7.

This signal is emitted when access to requestUrl requires authentication. authenticator should be used to pass the user name and password for the connection.

This signal is emitted when an invalid certificate error is raised while loading a given request.

The certificateError parameter contains information about the certificate and details of the error, it also provides the way to ignore the error and complete the request or stop loading the request.

See Also▲

This function is called when the web content requests a file name, for example as a result of the user clicking on a file upload button in an HTML form.

mode indicates whether only one file or multiple files are expected to be returned.

A suggested filename may be provided as the first entry of oldFiles. acceptedMimeTypes is ignored by the default implementation, but might be used by overrides.

This function is called to create a new window of the specified type. For example, when a JavaScript program requests to open a document in a new window.

If the new window can be created, the new window's QWebEnginePage is returned; otherwise a null pointer is returned.

If the view associated with the web page is a QWebEngineView object, then the default implementation forwards the request to QWebEngineView::createWindow(); otherwise it returns a null pointer.

If this call is not implemented or does not return a new page, newWindowRequested() is emitted to handle the request.

See Also▲

Returns the page that is hosting the developer tools of this page, if any.

Returns nullptr if no developer tools page is set.

This function was introduced in Qt 5.11.

See Also▲

Downloads the resource from the location given by url to a local file.

If filename is given, it is used as the suggested file name. If it is relative, the file is saved in the standard download location with the given name. If it is a null or empty QString, the default file name is used.

This will emit QWebEngineProfile::downloadRequested() after the download has started.

This function was introduced in Qt 5.10.

Reimplements: QObject::event(QEvent *e).

This signal is emitted when the web site identified by securityOrigin cancels a previously issued request to make use of feature.

See Also▲

This signal is emitted when the web site identified by securityOrigin requests to make use of the resource or device identified by feature.

See Also▲

Finds the specified string, subString, in the page, using the given options. The findTextFinished() signal is emitted when a string search is completed.

To clear the search highlight, just pass an empty string.

The resultCallback must take a QWebEngineFindTextResult parameter.

For example:

    m_view->page()->findText(QStringLiteral("Qt"), QWebEnginePage::FindFlags(), [this](bool found) {
        if (!found) QMessageBox::information(m_view, QString(), QStringLiteral("No occurrences found"));
    });

See Also▲

This signal is emitted when a search string search on a page is completed. result is the result of the string search.

This function was introduced in Qt 5.14.

See Also▲

This signal is emitted when the web page issues the request to enter fullscreen mode for a web-element, usually a video element.

The request object fullScreenRequest can be used to accept or reject the request.

If the request is accepted the element requesting fullscreen will fill the viewport, but it is up to the application to make the view fullscreen or move the page to a view that is fullscreen.

See Also▲

This signal is emitted whenever the document wants to change the position and size of the page to geom. This can happen for example through JavaScript.

window->setGeometry(geom.marginsRemoved(window->frameMargins()));

Returns a pointer to the view's history of navigated web pages.

This signal is emitted when the icon ("favicon") associated with the page is changed. The new icon is specified by icon.

This function was introduced in Qt 5.7.

See Also▲

This signal is emitted when the URL of the icon ("favicon") associated with the page is changed. The new URL is specified by url.

See Also▲

Returns the page this page is inspecting, if any.

Returns nullptr if this page is not a developer tools page.

This function was introduced in Qt 5.11.

See Also▲

This function is called whenever a JavaScript program running in a frame affiliated with securityOrigin calls the alert() function with the message msg.

The default implementation shows the message, msg, with QMessageBox::information.

This function is called whenever a JavaScript program running in a frame affiliated with securityOrigin calls the confirm() function with the message msg. Returns true if the user confirms the message; otherwise returns false.

It is also called when the onbeforeunload handler is requesting a confirmation before leaving a page.

The default implementation executes the query using QMessageBox::information with QMessageBox::Ok and QMessageBox::Cancel buttons.

This function is called when a JavaScript program tries to print the message to the web browser's console.

For example, in case of evaluation errors the source URL may be provided in sourceID as well as the lineNumber.

level indicates the severity of the event that triggered the message. That is, whether it was triggered by an error or a less severe event.

Since Qt 5.6, the default implementation logs the messages in a js logging category.

See Also▲

This function is called whenever a JavaScript program running in a frame affiliated with securityOrigin tries to prompt the user for input. The program may provide an optional message, msg, as well as a default value for the input in defaultValue.

If the prompt was cancelled by the user, the implementation should return false; otherwise the result should be written to result and true should be returned. If the prompt was not cancelled by the user, the implementation should return true and the result string must not be null.

The default implementation uses QInputDialog::getText().

This signal is emitted when the mouse hovers over a link. url contains the target URL of the link.

Loads url into this page.

See Also▲

Issues the specified request and loads the response.

This function was introduced in Qt 5.9.

See Also▲

This signal is emitted when the page finishes loading content. This signal is independent of script execution or page rendering. ok will indicate whether the load was successful or any error occurred.

See Also▲

This signal is emitted when the global progress status changes. The current value is provided by progress and scales from 0 to 100, which is the default range of QProgressBar. It accumulates changes from all the child frames.

This signal is emitted when a page starts loading content.

See Also▲

This signal is emitted when loading the page specified by loadingInfo begins, ends, or fails.

This function was introduced in Qt 6.2.

This signal is emitted on navigation together with the call the acceptNavigationRequest(). It can be used to accept or ignore the request. The default is to accept.

This function was introduced in Qt 6.2.

See Also▲

This signal is emitted when request is issued to load a page in a separate web engine window. This can either be because the current page requested it explicitly through a JavaScript call to window.open, or because the user clicked on a link 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 openIn() with the new page on the request. If this signal is not handled, the requested load will fail.

This function was introduced in Qt 6.2.

See Also▲

This signal is emitted when printing the web page into a PDF file has finished. filePath will contain the path the file was requested to be created at, and success will be true if the file was successfully created and false otherwise.

See Also▲

Renders the current content of the page into a PDF document and saves it in the location specified in filePath. The page size and orientation of the produced PDF document are taken from the values specified in layout, while the range of pages printed is taken from ranges with the default being printing all 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 signal pdfPrintingFinished().

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

See Also▲

Renders the current content of the page into a PDF document and returns a byte array containing the PDF data as parameter to resultCallback. The page size and orientation of the produced PDF document are taken from the values specified in layout, while the range of pages printed is taken from ranges with the default being printing all pages.

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

Returns the web engine profile the page belongs to.

This function was introduced in Qt 5.5.

This signal is emitted when access to requestUrl via proxyHost requires authentication for the proxy. authenticator should be used to pass the user name and password for the connection.

This signal is emitted when the web page requests larger persistent storage than the application's current allocation in File System API. The default quota is 0 bytes.

The request object quotaRequest can be used to accept or reject the request.

This function was introduced in Qt 5.11.

This signal is emitted when the page's audible state, recentlyAudible, changes, because the audio is played or stopped.

This function was introduced in Qt 5.7.

This signal is emitted when the web page tries to register a custom protocol using the registerProtocolHandler API.

The request object request can be used to accept or reject the request:

void WebView::handleRegisterProtocolHandlerRequested(
        QWebEngineRegisterProtocolHandlerRequest request)
{
    auto answer = QMessageBox::question(window(), tr("Permission Request"),
                                        tr("Allow %1 to open all %2 links?")
                                                .arg(request.origin().host())
                                                .arg(request.scheme()));
    if (answer == QMessageBox::Yes)
        request.accept();
    else
        request.reject();
}

This function was introduced in Qt 5.11.

This signal is emitted when the underlying render process PID, pid, changes.

This function was introduced in Qt 5.15.

This signal is emitted when the render process is terminated with a non-zero exit status. terminationStatus is the termination status of the process and exitCode is the status code with which the process terminated.

This function was introduced in Qt 5.6.

Replace the current misspelled word with replacement.

The current misspelled word can be found in QWebEngineContextMenuRequest::misspelledWord(), and suggested replacements in QWebEngineContextMenuRequest::spellCheckerSuggestions().

This function was introduced in Qt 5.8.

Save the currently loaded web page to disk.

The web page is saved to filePath in the specified format.

This is a short cut for the following actions:

• Trigger the Save web action.

• Accept the next download item and set the specified file path and save format.

This function issues an asynchronous download request for the web page and returns immediately.

This function was introduced in Qt 5.8.

See Also▲

Returns the collection of scripts that are injected into the page.

In addition, a page might also execute scripts added through QWebEngineProfile::scripts().

See Also▲

This signal is emitted when a web site requests an SSL client certificate, and one or more were found in system's client certificate store.

Handling the signal is asynchronous, and loading will be waiting until a certificate is selected, or the last copy of clientCertificateSelection is destroyed.

If the signal is not handled, clientCertificateSelection is automatically destroyed, and loading will continue without a client certificate.

This function was introduced in Qt 5.12.

See Also▲

This signal is emitted whenever the selection changes, either interactively or programmatically. For example, by calling triggerAction() with a selection action.

See Also▲

Sets the content of the web page to data. If the mimeType argument is empty, it is assumed that the content is text/plain,charset=US-ASCII.

External objects referenced in the content are located relative to baseUrl.

The data is loaded immediately; external objects are loaded asynchronously.

See Also▲

Binds devToolsPage to be the developer tools of this page. Triggers devToolsPage to navigate to an internal URL with the developer tools.

This is the same as calling setInspectedPage() on devToolsPage with this as argument.

This function was introduced in Qt 5.11.

See Also▲

Sets the permission for the web site identified by securityOrigin to use feature to policy.

See Also▲

Sets the content of this page to html. baseUrl is optional and used to resolve relative URLs in the document, such as referenced images or stylesheets.

The html is loaded immediately; external objects are loaded asynchronously.

If a script in the html runs longer than the default script timeout (currently 10 seconds), for example due to being blocked by a modal JavaScript alert dialog, this method will return as soon as possible after the timeout and any subsequent html will be loaded asynchronously.

When using this method, the web engine assumes that external resources, such as JavaScript programs or style sheets, are encoded in UTF-8 unless otherwise specified. For example, the encoding of an external script can be specified through the charset attribute of the HTML script tag. It is also possible for the encoding to be specified by the web server.

This is a convenience function equivalent to setContent(html, "text/html", baseUrl).

See Also▲

Navigates this page to an internal URL that is the developer tools of page.

This is the same as calling setDevToolsPage() on page with this as argument.

This function was introduced in Qt 5.11.

See Also▲

Registers the request interceptor interceptor to intercept URL requests.

The page does not take ownership of the pointer. This interceptor is called after any interceptors on the profile, and unlike profile interceptors, only URL requests from this page are intercepted.

To unset the request interceptor, set a nullptr.

This function was introduced in Qt 5.13.

See Also▲

Sets the web channel instance to be used by this page to channel and connects it to web engine's transport using Chromium IPC messages. The transport is exposed in the JavaScript world worldId as qt.webChannelTransport, which should be used when using the Qt WebChannel JavaScript API.

This function was introduced in Qt 5.7.

See Also▲

Returns a pointer to the page's settings object.

This signal is emitted whenever the title of the page changes. The title string specifies the new title.

See Also▲

Asynchronous method to retrieve the page's content as HTML, enclosed in HTML and BODY tags. Upon successful completion, resultCallback is called with the page's content.

See Also▲

Asynchronous method to retrieve the page's content converted to plain text, completely stripped of all HTML formatting. Upon successful completion, resultCallback is called with the page's content.

See Also▲

This function can be called to trigger the specified action. It is also called by Qt WebEngine if the user triggers the action, for example through a context menu item.

If action is a checkable action, then checked specifies whether the action is toggled or not.

See Also▲

This signal is emitted with the URL of the page when the page title is received. The new URL is specified by url.

See Also▲

Returns a pointer to the web channel instance used by this page or a null pointer if none was set. This channel automatically uses the internal web engine transport mechanism over Chromium IPC that is exposed in the JavaScript context of this page as qt.webChannelTransport.

This function was introduced in Qt 5.5.

See Also▲

This signal is emitted whenever the page requests the web browser window to be closed, for example through the JavaScript window.close() call.

See Also▲