QWebEnginePage Class

The QWebEnginePage class provides an object to view and edit web documents. More...

Header: #include <QWebEnginePage>
Inherits: QObject.

Public Types

enum Feature { MediaAudioCapture, MediaVideoCapture, MediaAudioVideoCapture }
enum FileSelectionMode { FileSelectOpen, FileSelectOpenMultiple }
enum FindFlag { FindBackward, FindCaseSensitively }
flags FindFlags
enum JavaScriptConsoleMessageLevel { InfoMessageLevel, WarningMessageLevel, ErrorMessageLevel }
enum PermissionPolicy { PermissionUnknown, PermissionGrantedByUser, PermissionDeniedByUser }
enum WebAction { NoWebAction, Back, Forward, Stop, ..., PasteAndMatchStyle }
enum WebWindowType { WebBrowserWindow, WebBrowserTab, WebDialog }

Properties

  • 1 property inherited from QObject

Public Functions

QWebEnginePage(QObject * parent = 0)
~QWebEnginePage()
QAction * action(WebAction action) const
QMenu * createStandardContextMenu()
void findText(const QString & subString, FindFlags options = 0)
void findText(const QString & subString, FindFlags options, FunctorOrLambda resultCallback)
bool hasSelection() const
QWebEngineHistory * history() const
QUrl iconUrl() const
void load(const QUrl & url)
QUrl requestedUrl() const
void runJavaScript(const QString & scriptSource)
void runJavaScript(const QString & scriptSource, FunctorOrLambda resultCallback)
QString selectedText() const
void setContent(const QByteArray & data, const QString & mimeType = QString(), const QUrl & baseUrl = QUrl())
void setFeaturePermission(const QUrl & securityOrigin, Feature feature, PermissionPolicy policy)
void setHtml(const QString & html, const QUrl & baseUrl = QUrl())
void setUrl(const QUrl & url)
void setView(QWidget * view)
void setZoomFactor(qreal factor)
QWebEngineSettings * settings() const
QString title() const
void toHtml(FunctorOrLambda resultCallback) const
void toPlainText(FunctorOrLambda resultCallback) const
virtual void triggerAction(WebAction action, bool checked = false)
QUrl url() const
QWidget * view() const
qreal zoomFactor() const

Reimplemented Public Functions

virtual bool event(QEvent * e)
  • 31 public functions inherited from QObject

Signals

void authenticationRequired(const QUrl & requestUrl, QAuthenticator * authenticator)
void featurePermissionRequestCanceled(const QUrl & securityOrigin, QWebEnginePage::Feature feature)
void featurePermissionRequested(const QUrl & securityOrigin, QWebEnginePage::Feature feature)
void geometryChangeRequested(const QRect & geom)
void iconUrlChanged(const QUrl & url)
void linkHovered(const QString & url)
void loadFinished(bool ok)
void loadProgress(int progress)
void loadStarted()
void proxyAuthenticationRequired(const QUrl & requestUrl, QAuthenticator * authenticator, const QString & proxyHost)
void selectionChanged()
void titleChanged(const QString & title)
void urlChanged(const QUrl & url)
void windowCloseRequested()

Protected Functions

virtual bool certificateError(const QWebEngineCertificateError & certificateError)
virtual QStringList chooseFiles(FileSelectionMode mode, const QStringList & oldFiles, const QStringList & acceptedMimeTypes)
virtual QWebEnginePage * createWindow(WebWindowType type)
virtual void javaScriptAlert(const QUrl & securityOrigin, const QString & msg)
virtual bool javaScriptConfirm(const QUrl & securityOrigin, const QString & msg)
virtual void javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level, const QString & message, int lineNumber, const QString & sourceID)
virtual bool javaScriptPrompt(const QUrl & securityOrigin, const QString & msg, const QString & defaultValue, QString * result)
  • 9 protected functions inherited from QObject

Additional Inherited Members

  • 1 public slot inherited from QObject
  • 11 static public members inherited from QObject

Detailed Description

The QWebEnginePage class provides an object to view and edit web documents.

QWebEnginePage holds a main frame responsible for web content, the history of navigated links and actions.

QWebEnginePage's API is very similar to QWebEngineView, as you are still provided with common functions like action() (known as pageAction() in QWebEngineView), triggerAction(), and findText().

A page can be loaded using load() or setUrl(). Alternatively, if you have the HTML content readily available, you can use setHtml() instead.

The QWebEnginePage class also offers methods to retrieve both the URL currently loaded by its main frame (see url()) as well as the URL originally requested to be loaded (see requestedUrl()). These methods make possible the retrieval of the URL before and after a DNS resolution or a redirection occurs during the load process. The requestedUrl() also matches to the URL added to the page history (QWebEngineHistory) if load is successful.

The title of an HTML page can be accessed with the title() property. Additionally, a page may also specify an icon, which can be accessed using the icon() property. If the title or the icon changes, the corresponding titleChanged() and iconChanged() signals will be emitted. The zoomFactor() property can be used to change the overall size of the content displayed in the page.

The loadStarted() signal is emitted when the page begins to load.The loadProgress() signal, on the other hand, is emitted whenever an element of the web page completes loading, such as an embedded image, a script, etc. Finally, the loadFinished() signal is emitted when the page contents are loaded completely, independent of script execution or page rendering. Its argument, either true or false, indicates whether or not the load operation succeeded.

Member Type Documentation

enum QWebEnginePage::​Feature

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

ConstantValueDescription
QWebEnginePage::MediaAudioCapture2Audio capture devices such a microphones
QWebEnginePage::MediaVideoCapture3Video devices, e.g. cameras
QWebEnginePage::MediaAudioVideoCapture4Both Audio and Video capture devices.

See also featurePermissionRequested(), featurePermissionRequestCanceled(), setFeaturePermission(), and PermissionPolicy.

enum QWebEnginePage::​FileSelectionMode

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

ConstantValueDescription
QWebEnginePage::FileSelectOpen0The implementation should return only one file name.
QWebEnginePage::FileSelectOpenMultiple1The implementation may return multiple file names.

See also chooseFiles().

enum QWebEnginePage::​FindFlag
flags QWebEnginePage::​FindFlags

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

ConstantValueDescription
QWebEnginePage::FindBackward1Searches backwards instead of forwards.
QWebEnginePage::FindCaseSensitively2By default findText() works case insensitive. Specifying this option changes the behavior to a case sensitive find operation.

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

enum QWebEnginePage::​JavaScriptConsoleMessageLevel

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

ConstantValueDescription
QWebEnginePage::InfoMessageLevel0The message is purely informative and can safely be ignored.
QWebEnginePage::WarningMessageLevel1The message informs about unexpected behaviors or errors that may need attention.
QWebEnginePage::ErrorMessageLevel2The message indicates there has been an error.

enum QWebEnginePage::​PermissionPolicy

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

ConstantValueDescription
QWebEnginePage::PermissionUnknown0It is unknown whether the user grants or denies permission.
QWebEnginePage::PermissionGrantedByUser1The user has granted permission.
QWebEnginePage::PermissionDeniedByUser2The user has denied permission.

See also featurePermissionRequested(), featurePermissionRequestCanceled(), setFeaturePermission(), and Feature.

enum QWebEnginePage::​WebAction

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

ConstantValueDescription
QWebEnginePage::NoWebAction-1No action is triggered.
QWebEnginePage::Back0Navigate back in the history of navigated links.
QWebEnginePage::Forward1Navigate forward in the history of navigated links.
QWebEnginePage::Stop2Stop loading the current page.
QWebEnginePage::Reload3Reload the current page.
QWebEnginePage::ReloadAndBypassCache10Reload the current page, but do not use any local cache.
QWebEnginePage::Cut4Cut the content currently selected into the clipboard.
QWebEnginePage::Copy5Copy the content currently selected into the clipboard.
QWebEnginePage::Paste6Paste content from the clipboard.
QWebEnginePage::Undo7Undo the last editing action.
QWebEnginePage::Redo8Redo the last editing action.
QWebEnginePage::SelectAll9Selects all content.
QWebEnginePage::PasteAndMatchStyle11Paste content from the clipboard with current style.

enum QWebEnginePage::​WebWindowType

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

ConstantValueDescription
QWebEnginePage::WebBrowserWindow0The page should be opened in a complete web browser window.
QWebEnginePage::WebBrowserTab1The page should be opened as a web browser tab.
QWebEnginePage::WebDialog2The page should be opened in a window without decoration.

Property Documentation

hasSelection : const bool

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

Access functions:

bool hasSelection() const

See also selectionChanged().

iconUrl : const QUrl

This property holds the url of the icon associated with the frame currently viewed.

Access functions:

QUrl iconUrl() const

See also iconUrlChanged().

requestedUrl : const QUrl

The URL requested to loaded by the frame currently viewed. The URL may differ from the one returned by url() if a DNS resolution or a redirection occurs.

Access functions:

QUrl requestedUrl() const

See also url() and setUrl().

selectedText : const QString

This property holds the text currently selected.

By default, this property contains an empty string.

Access functions:

QString selectedText() const

See also selectionChanged().

title : const QString

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

Access functions:

QString title() const

See also titleChanged().

url : QUrl

This property holds the url of the frame currently viewed.

Setting this property clears the view and loads the URL.

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

Access functions:

QUrl url() const
void setUrl(const QUrl & url)

See also urlChanged().

zoomFactor : qreal

This property holds the zoom factor for the main frame.

Access functions:

qreal zoomFactor() const
void setZoomFactor(qreal factor)

Member Function Documentation

QWebEnginePage::​QWebEnginePage(QObject * parent = 0)

Constructs an empty QWebEnginePage with parent parent.

QWebEnginePage::​~QWebEnginePage()

Destroys the web page.

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)

[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 a HTML form.

mode indicates whether only one file or multiples 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()

This function 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 whenever the WebEngine wants to create a new window of the given 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's createWindow() function; otherwise it returns a null pointer.

Note: In the cases when the window creation is being triggered by JavaScript, apart from reimplementing this method application must also set the JavaScriptCanOpenWindows attribute of QWebEngineSettings to true in order for it 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 = 0)

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

To clear the selection, 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 selection, 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::​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 main frame 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 whenever a JavaScript program tries to print a 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, i.e. if it was triggered by an error or a less severe event.

The default implementation prints nothing.

[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 frame.

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

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

void QWebEnginePage::​runJavaScript(const QString & scriptSource)

Runs the JavaScript code contained in scriptSource.

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

Runs the JavaScript code contained in scriptSource.

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

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

[signal] void QWebEnginePage::​selectionChanged()

This signal is emitted whenever the selection changes, either interactively or programmatically (e.g. 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's main frame to the specified content 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 frame.

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.

See also featurePermissionRequested() and featurePermissionRequestCanceled().

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

Sets the content of this page's main frame 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 WebEngie 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 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 frame.

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

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

void QWebEnginePage::​setView(QWidget * view)

Sets the view that is associated with the web page.

See also view().

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 main frame 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 specified 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 main frame when the main frame's 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().

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

© 2015 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.