Member Function Documentation

QWebEnginePage::QWebEnginePage(QObject *parent = Q_NULLPTR)

Constructs an empty QWebEnginePage with the parent parent.

QWebEnginePage::QWebEnginePage(QWebEngineProfile *profile, QObject *parent = Q_NULLPTR)

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.

QWebEnginePage::~QWebEnginePage()

Destroys the web page.

[virtual protected] bool QWebEnginePage::acceptNavigationRequest(const QUrl &url, NavigationType type, bool isMainFrame)

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.

This function is called for absolute URLs that are prefixed with http:// or https:// and for unrecognized schemes, such as mailto:, which will be handled by QDesktopServices if accepted. To have this function called also upon receiving navigation requests to local URLs, prefix the URLs with http://.

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.

This function was introduced in Qt 5.5.

QAction *QWebEnginePage::action(WebAction action) const

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 triggerAction().

[signal] void QWebEnginePage::authenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator)

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

[virtual protected] bool QWebEnginePage::certificateError(const QWebEngineCertificateError &certificateError)

This function is called 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.

Return true to ignore the error and complete the request. Return false to stop loading the request.

See also QWebEngineCertificateError.

[virtual protected] QStringList QWebEnginePage::chooseFiles(FileSelectionMode mode, const QStringList &oldFiles, const QStringList &acceptedMimeTypes)

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.

QMenu *QWebEnginePage::createStandardContextMenu()

Creates the standard context menu which is shown when the user clicks on the web page with the right mouse button. It is called from the default contextMenuEvent() handler. The popup menu's ownership is transferred to the caller.

[virtual protected] QWebEnginePage *QWebEnginePage::createWindow(WebWindowType type)

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.

Note: In the cases when the window creation is being triggered by JavaScript, apart from reimplementing this method the application must also set QWebEngineSettings::JavascriptCanOpenWindows to true in order for the method to get called.

See also QWebEngineView::createWindow().

[virtual] bool QWebEnginePage::event(QEvent *e)

Reimplemented from QObject::event().

[signal] void QWebEnginePage::featurePermissionRequestCanceled(const QUrl &securityOrigin, QWebEnginePage::Feature feature)

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

See also featurePermissionRequested() and setFeaturePermission().

[signal] void QWebEnginePage::featurePermissionRequested(const QUrl &securityOrigin, QWebEnginePage::Feature feature)

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

See also featurePermissionRequestCanceled() and setFeaturePermission().

void QWebEnginePage::findText(const QString &subString, FindFlags options = FindFlags())

Finds the specified string, subString, in the page, using the given options.

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

void QWebEnginePage::findText(const QString &subString, FindFlags options, FunctorOrLambda resultCallback)

Finds the specified string, subString, in the page, using the given options.

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

The resultCallback must take a boolean parameter. It will be called with a value of true if the subString was found; otherwise the callback value will be false.

For example:

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

[signal] void QWebEnginePage::fullScreenRequested(QWebEngineFullScreenRequest request)

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 request 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 QWebEngineSettings::FullScreenSupportEnabled.

[signal] void QWebEnginePage::geometryChangeRequested(const QRect &geom)

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.

QWebEngineHistory *QWebEnginePage::history() const

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

[signal] void QWebEnginePage::iconUrlChanged(const QUrl &url)

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

See also iconUrl().

[virtual protected] void QWebEnginePage::javaScriptAlert(const QUrl &securityOrigin, const QString &msg)

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.

[virtual protected] bool QWebEnginePage::javaScriptConfirm(const QUrl &securityOrigin, const QString &msg)

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.

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

[virtual protected] void QWebEnginePage::javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level, const QString &message, int lineNumber, const QString &sourceID)

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 Console Logging.

[virtual protected] bool QWebEnginePage::javaScriptPrompt(const QUrl &securityOrigin, const QString &msg, const QString &defaultValue, QString *result)

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

[signal] void QWebEnginePage::linkHovered(const QString &url)

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

void QWebEnginePage::load(const QUrl &url)

Loads url into this page.

Note: The view remains the same until enough data has arrived to display the new URL.

See also setUrl(), setHtml(), and setContent().

[signal] void QWebEnginePage::loadFinished(bool ok)

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 loadStarted().

[signal] void QWebEnginePage::loadProgress(int progress)

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.

[signal] void QWebEnginePage::loadStarted()

This signal is emitted when a page starts loading content.

See also loadFinished().

QWebEngineProfile *QWebEnginePage::profile() const

Returns the web engine profile the page belongs to.

This function was introduced in Qt 5.5.

[signal] void QWebEnginePage::proxyAuthenticationRequired(const QUrl &requestUrl, QAuthenticator *authenticator, const QString &proxyHost)

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.

[signal] void QWebEnginePage::renderProcessTerminated(RenderProcessTerminationStatus terminationStatus, int exitCode)

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.

void QWebEnginePage::runJavaScript(const QString &scriptSource, FunctorOrLambda resultCallback)

Runs the JavaScript code contained in scriptSource.

The script will run in the same world as other scripts that are part of the loaded site.

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(); });

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

See scripts() for an alternative API to inject scripts.

void QWebEnginePage::runJavaScript(const QString &scriptSource)

This function overloads runJavaScript().

This convenience function runs the JavaScript code contained in scriptSource.

QWebEngineScriptCollection &QWebEnginePage::scripts()

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 QWebEngineScriptCollection and QWebEngineScript.

[signal] void QWebEnginePage::selectionChanged()

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

See also selectedText().

void QWebEnginePage::setContent(const QByteArray &data, const QString &mimeType = QString(), const QUrl &baseUrl = QUrl())

Sets the content of this page to data. If the mimeType argument is empty, it is currently assumed that the content is HTML but in future versions we may introduce auto-detection.

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

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

Note: This method will not affect session or global history for the page.

Warning: The content will be percent encoded before being sent to the renderer via IPC. This may increase its size. The maximum size of the percent encoded content is 2 megabytes minus 6 bytes plus the length of the mime type string.

See also toHtml() and setHtml().

void QWebEnginePage::setFeaturePermission(const QUrl &securityOrigin, Feature feature, PermissionPolicy policy)

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

Note: Call this method on the featurePermissionRequested() signal, as it is meant to serve pending feature requests only. Setting feature permissions ahead of a request has no effect.

See also featurePermissionRequested() and featurePermissionRequestCanceled().

void QWebEnginePage::setHtml(const QString &html, const QUrl &baseUrl = QUrl())

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

Note: This method will not affect session or global history for the page.

Warning: This function works only for HTML, for other mime types (such as XHTML and SVG) setContent() should be used instead.

Warning: The content will be percent encoded before being sent to the renderer via IPC. This may increase its size. The maximum size of the percent encoded content is 2 megabytes minus 30 bytes.

See also toHtml(), setContent(), and load().

void QWebEnginePage::setView(QWidget *view)

Sets the view that is associated with the web page.

See also view().

void QWebEnginePage::setWebChannel(QWebChannel *channel)

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 context of this page as qt.webChannelTransport, which should be used when using the Qt WebChannel JavaScript API.

Note: The page does not take ownership of the channel object.

This function was introduced in Qt 5.5.

See also webChannel().

QWebEngineSettings *QWebEnginePage::settings() const

Returns a pointer to the page's settings object.

See also QWebEngineSettings::globalSettings().

[signal] void QWebEnginePage::titleChanged(const QString &title)

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

See also title().

void QWebEnginePage::toHtml(FunctorOrLambda resultCallback) const

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.

Note: resultCallback can be any of a function pointer, a functor or a lambda, and it is expected to take a QString parameter.

See also setHtml() and toPlainText().

void QWebEnginePage::toPlainText(FunctorOrLambda resultCallback) const

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.

Note: resultCallback can be any of a function pointer, a functor or a lambda, and it is expected to take a QString parameter.

See also toHtml().

[virtual] void QWebEnginePage::triggerAction(WebAction action, bool checked = false)

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 action().

[signal] void QWebEnginePage::urlChanged(const QUrl &url)

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 url().

QWidget *QWebEnginePage::view() const

Returns the view widget that is associated with the web page.

See also setView().

QWebChannel *QWebEnginePage::webChannel() const

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

[signal] void QWebEnginePage::windowCloseRequested()

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 QWebEnginePage::RequestClose.