Qt 5.212.0
Qt 5.212.0 Reference Documentation

WebView QML Type

A WebView renders web content within a QML application. More...

Import Statement: import QtWebKit 3.0

List of all members, including inherited members

Properties

ErrorDomain : enumeration
LoadStatus : enumeration
NavigationRequestAction : enumeration
NavigationType : enumeration
canGoBack : bool
canGoForward : bool
icon : url
loadProgress : int
loading : bool
title : string
url : url

Signals

onLinkHovered(hoveredUrl, hoveredTitle)
onLoadingChanged(loadRequest)
onNavigationRequested(request)

Methods

void goBack()
void goForward()
void loadHtml(string html, url baseUrl, url unreachableUrl)
void reload()
void stop()

Detailed Description

WebView allows an application to load pages either by URL or an HTML string, and navigate within the session history. By default, links to different pages are loaded within the same WebView, but applications can choose to delegate those links to other functions.

The following example loads a web page, responds to session history context, and intercepts requests for external links. It also makes use of ScrollView from Qt Quick Controls to add scroll bars for the content area.

import QtQuick 2.0
import QtQuick.Controls 1.0
import QtWebKit 3.0

ScrollView {
    width: 1280
    height: 720
    WebView {
        id: webview
        url: "http://qt-project.org"
        anchors.fill: parent
        onNavigationRequested: {
            // detect URL scheme prefix, most likely an external link
            var schemaRE = /^\w+:/;
            if (schemaRE.test(request.url)) {
                request.action = WebView.AcceptRequest;
            } else {
                request.action = WebView.IgnoreRequest;
                // delegate request.url here
            }
        }
    }
}

Property Documentation

ErrorDomain : enumeration

Details various high-level error types.

Constant	Description
InternalErrorDomain	Content fails to be interpreted by Qt WebKit.
NetworkErrorDomain	Error results from faulty network connection.
HttpErrorDomain	Error is produced by server.
DownloadErrorDomain	Error in saving file.
NoErrorDomain	Unspecified fallback error.

LoadStatus : enumeration

Reflects a page's load status.

Constant	Description
LoadStartedStatus	Page is currently loading.
LoadSucceededStatus	Page has successfully loaded, and is not currently loading.
LoadFailedStatus	Page has failed to load, and is not currently loading.

NavigationRequestAction : enumeration

Specifies a policy when navigating a link to an external page.

Constant	Description
AcceptRequest	Allow navigation to external pages within the web view.
IgnoreRequest	Suppress navigation to new pages within the web view.

NavigationType : enumeration

Distinguishes context for various navigation actions.

Constant	Description
LinkClickedNavigation	Navigation via link.
FormSubmittedNavigation	Form data is posted.
BackForwardNavigation	Navigation back and forth within session history.
ReloadNavigation	The current page is reloaded.
FormResubmittedNavigation	Form data is re-posted.
OtherNavigation	Unspecified fallback method of navigation.

canGoBack : bool

Returns true if there are prior session history entries, false otherwise.

canGoForward : bool

Returns true if there are subsequent session history entries, false otherwise.

icon : url

The location of the currently displaying Web site icon, also known as favicon or shortcut icon. This read-only URL corresponds to the image used within a mobile browser application to represent a bookmarked page on the device's home screen.

This example uses the icon property to build an Image element:

Image {
    id: appIcon
    source: webView.icon != "" ? webView.icon : "fallbackFavIcon.png";
    ...
}

loadProgress : int

The amount of the page that has been loaded, expressed as an integer percentage in the range from 0 to 100.

loading : bool

Returns true if the HTML page is currently loading, false otherwise.

title : string

The title of the currently displaying HTML page, a read-only value that reflects the contents of the <title> tag.

url : url

The location of the currently displaying HTML page. This writable property offers the main interface to load a page into a web view. It functions the same as the window.location DOM property.

See also WebView::loadHtml().

Signal Documentation

onLinkHovered(hoveredUrl, hoveredTitle)

Within a mouse-driven interface, this signal is emitted when a mouse pointer passes over a link, corresponding to the mouseover DOM event. (May also occur in touch interfaces for mouseover events that are not cancelled with preventDefault().) The hoveredUrl provides the link's location, and the hoveredTitle is any avalable link text.

onLoadingChanged(loadRequest)

Occurs when any page load begins, ends, or fails. Various read-only parameters are available on the loadRequest:

url: the location of the resource that is loading.
status: Reflects one of three load states: LoadStartedStatus, LoadSucceededStatus, or LoadFailedStatus. See WebView::LoadStatus.
errorString: description of load error.
errorCode: HTTP error code.
errorDomain: high-level error types, one of NetworkErrorDomain, HttpErrorDomain, InternalErrorDomain, DownloadErrorDomain, or NoErrorDomain. See WebView::ErrorDomain.

See also WebView::loading.

onNavigationRequested(request)

Occurs for various kinds of navigation. If the application listens for this signal, it must set the request.action to either of the following WebView::NavigationRequestAction enum values:

AcceptRequest: Allow navigation to external pages within the web view. This represents the default behavior when no listener is active.
IgnoreRequest: Suppress navigation to new pages within the web view. (The listener may then delegate navigation externally to the browser application.)

The request also provides the following read-only values:

url: The location of the requested page.
navigationType: contextual information, one of LinkClickedNavigation, BackForwardNavigation, ReloadNavigation, FormSubmittedNavigation, FormResubmittedNavigation, or OtherNavigation enum values. See WebView::NavigationType.
keyboardModifiers: potential states for Qt::KeyboardModifier.
mouseButton: potential states for Qt::MouseButton.

Method Documentation

void goBack()

Go backward within the browser's session history, if possible. (Equivalent to the window.history.back() DOM method.)

See also WebView::canGoBack.

void goForward()

Go forward within the browser's session history, if possible. (Equivalent to the window.history.forward() DOM method.)

void loadHtml(string html, url baseUrl, url unreachableUrl)

Loads the specified html as the content of the web view.

(This method offers a lower-level alternative to the url property, which references HTML pages via URL.)

External objects such as stylesheets or images referenced in the HTML document are located relative to baseUrl. For example if provided html was originally retrieved from http://www.example.com/documents/overview.html and that was the base url, then an image referenced with the relative url diagram.png would be looked for at http://www.example.com/documents/diagram.png.

It is important to keep in mind that the html string will be converted to UTF-16 internally. Textual resources, such as scripts or style sheets, will be treated as UTF-16 as well, unless they have an explicit charset property in their referencing tag.

If an unreachableUrl is passed it is used as the url for the loaded content. This is typically used to display error pages for a failed load.

See also WebView::url.

void reload()

Reload the current page. (Equivalent to the window.location.reload() DOM method.)

void stop()

Stop loading the current page.

Contents