WebView

An embedded web browser.

../../../_images/webview-cocoa.png

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

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.

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

  • 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:

    $ defaults write com.example.appname WebKitDeveloperExtras -bool true

    Substituting com.example.appname with the bundle ID for your packaged app.

Reference

class toga.WebView(id=None, style=None, url=None, user_agent=None, on_webview_load=None)

Bases: Widget

Create a new WebView widget.

Parameters:

  • id – The ID for the widget.

  • style – A style object. If no style is provided, a default style will be applied to the widget.

  • url (str | None) – The full URL to load in the WebView. If not provided, an empty page will be displayed.

  • user_agent (str | None) – The user agent to use for web requests. If not provided, the default user agent for the platform will be used.

  • on_webview_load (callable | None) – A handler that will be invoked when the web view finishes loading.

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.

Parameters:

  • javascript – The JavaScript expression to evaluate.

  • on_result – DEPRECATED await the return value of this method.

Return type:

JavaScriptResult

async load_url(url)

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

Note: On Android, this method will return immediately.

Parameters:

url (str) – The URL to load.

property on_webview_load: callable

The handler to invoke when the web view finishes loading.

Rendering web content is a complex, multi-threaded 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.

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.

Parameters:

  • root_url (str) – A URL which will be returned by the url property, and used to resolve any relative URLs in the content.

  • content (str) – The HTML content for the WebView

property url: str | None

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.

property user_agent: str

The user agent to use for web requests.

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