WebView¶

An embedded web browser.

Usage¶

import toga

webview = toga.WebView()

# Request a URL be loaded in the webview.
webview.url = "https://beeware.org"

# Load a URL, and wait (non-blocking) for the page to complete loading
await webview.load_url("https://beeware.org")

# Load static HTML content into the wevbiew.
webview.set_content("https://example.com", "<html>...</html>")

System requirements¶

Using WebView on Windows 10 requires that your users have installed the Edge WebView2 Evergreen Runtime. This is installed by default on Windows 11.
Using WebView on Linux requires that the user has installed the system packages for WebKit2, plus the GObject Introspection bindings for WebKit2. The name of the system package required is distribution dependent:
Ubuntu 20.04; Debian 11: gir1.2-webkit2-4.0
Ubuntu 22.04+; Debian 12+: gir1.2-webkit2-4.1
Fedora: webkit2gtk4.1
Arch/Manjaro: webkit2gtk-4.1
OpenSUSE Tumbleweed: libwebkit2gtk3 typelib(WebKit2)
FreeBSD: webkit2-gtk3

WebView is not fully supported on GTK4. If you want to contribute to the GTK4 WebView implementation, you will require v6.0 of the WebKit2 libraries. This is provided by gir1.2-webkit-6.0 on Ubuntu/Debian, and webkitgtk6.0 on Fedora; for other distributions, consult your distribution's platform documentation.

Notes¶

Due to app security restrictions, WebView can only display http:// and https:// URLs, not file:// URLs. To serve local file content, run a web server on localhost using a background thread.
On macOS 13.3 (Ventura) and later, the content inspector for your app can be opened by running Safari, enabling the developer tools, and selecting your app's window from the "Develop" menu. On macOS versions prior to Ventura, the content inspector is not enabled by default, and is only available when your code is packaged as a full macOS app (e.g., with Briefcase). To enable debugging, run: > console > $ defaults write com.example.appname WebKitDeveloperExtras -bool true > > > Substituting com.example.appname with the bundle ID for your > packaged app.

Reference¶

toga.WebView ¶

WebView(
    id=None,
    style=None,
    url=None,
    content=None,
    user_agent=None,
    on_webview_load=None,
    **kwargs,
)

Bases: Widget

Create a new WebView widget.

PARAMETER	DESCRIPTION
`id`	The ID for the widget. TYPE: `str \| None` DEFAULT: `None`
`style`	A style object. If no style is provided, a default style will be applied to the widget. TYPE: `StyleT \| None` DEFAULT: `None`
`url`	The full URL to load in the WebView. If not provided, an empty page will be displayed. TYPE: `str \| None` DEFAULT: `None`
`content`	The HTML content to display in the WebView. If `content` is provided, the value of `url` will be used as the root URL for the content that is displayed; this URL will be used to resolve any relative URLs in the content. Note: On Android and Windows, if `content` is specified, any value provided for the `url` argument will be ignored. TYPE: `str \| None` DEFAULT: `None`
`user_agent`	The user agent to use for web requests. If not provided, the default user agent for the platform will be used. TYPE: `str \| None` DEFAULT: `None`
`on_webview_load`	A handler that will be invoked when the web view finishes loading. TYPE: `OnWebViewLoadHandler \| None` DEFAULT: `None`
`kwargs`	Initial style properties. DEFAULT: `{}`

content `property` `writable` ¶

content

A write-only attribute to set the HTML content currently displayed by the WebView.

web_view.content = "<html>..." is equivalent to calling web_view.set_content("", "<html>...").

RAISES	DESCRIPTION
`AttributeError`	If an attempt is made to read the page content.

cookies `property` ¶

cookies

Retrieve cookies from the WebView.

This is an asynchronous property. The value returned by this method must be awaited to obtain the cookies that are currently set.

Note: This property is not currently supported on Android or Linux.

RETURNS	DESCRIPTION
`CookiesResult`	An object that returns a CookieJar when awaited.

on_webview_load `property` `writable` ¶

on_webview_load

The handler to invoke when the web view finishes loading.

Rendering web content is a complex, multithreaded process. Although a page may have completed loading, there's no guarantee that the page has been fully rendered, or that the widget representation has been fully updated. The number of load events generated by a URL transition or content change can be unpredictable. An on_webview_load event should be interpreted as an indication that some change has occurred, not that a specific change has occurred, or that a specific change has been fully propagated into the rendered content.

Note: This is not currently supported on Android.

url `property` `writable` ¶

url

The current URL, or None if no URL is currently displayed.

After setting this property, it is not guaranteed that reading the property will immediately return the new value. To be notified once the URL has finished loading, use load_url or on_webview_load.

user_agent `property` `writable` ¶

user_agent

The user agent to use for web requests.

Note: On Windows, this property will return an empty string until the widget has finished initializing.

evaluate_javascript ¶

evaluate_javascript(javascript, on_result=None)

Evaluate a JavaScript expression.

This is an asynchronous method. There is no guarantee that the JavaScript has finished evaluating when this method returns. The object returned by this method can be awaited to obtain the value of the expression.

Note: On Android and Windows, no exception handling is performed. If a JavaScript error occurs, a return value of None will be reported, but no exception will be provided.

PARAMETER	DESCRIPTION
`javascript`	The JavaScript expression to evaluate. TYPE: `str`
`on_result`	DEPRECATED `await` the return value of this method. TYPE: `OnResultT \| None` DEFAULT: `None`

load_url `async` ¶

load_url(url)

Load a URL, and wait until the next on_webview_load event.

Note: On Android, this method will return immediately.

PARAMETER	DESCRIPTION
`url`	The URL to load. TYPE: `str`

set_content ¶

set_content(root_url, content)

Set the HTML content of the WebView.

Note: On Android and Windows, the root_url argument is ignored. Calling this method will set the url property to None.

PARAMETER	DESCRIPTION
`root_url`	A URL which will be returned by the `url` property, and used to resolve any relative URLs in the content. TYPE: `str`
`content`	The HTML content for the WebView TYPE: `str`

toga.widgets.webview.OnWebViewLoadHandler ¶

Bases: Protocol

call ¶

__call__(widget, **kwargs)

A handler to invoke when the WebView is loaded.

PARAMETER	DESCRIPTION
`widget`	The WebView that was loaded. TYPE: `WebView`
`kwargs`	Ensures compatibility with arguments added in future versions. TYPE: `Any` DEFAULT: `{}`

WebView¶

Usage¶

System requirements¶

Notes¶

Reference¶

toga.WebView ¶

content property writable ¶

cookies property ¶

on_webview_load property writable ¶

url property writable ¶

user_agent property writable ¶