tawebview package

This package is a plug-in replacement for toga.WebView which allows to monitor and optionally block the URLs being navigated to. The package is currently only supported on Windows.

TaWebView class

class tatogalib.ui.tawebview.TaWebView(id: str | None = None, style: StyleT | None = None, url: str | None = None, user_agent: str | None = None, on_navigation_starting=None, on_resource_requested=None, on_webview_load: OnWebViewLoadHandler | None = None)

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 – The full URL to load in the WebView. If not provided, an empty page will be displayed.

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

  • on_navigation_starting – A handler that will be invoked is raised when the TaWebView is requesting permission to navigate or redirect to a different URI.

  • on_resource_requested – A handler that will be invoked when the webview starts load (or reload)

  • on_webview_load – A handler that will be invoked when the web view finishes loading.

cancel_navigation(event)

Cancels the navigation being started

Parameters:

event (object) – The event object received in the on_navigation_starting handler

evaluate_javascript(javascript: str, on_result: OnResultT | None = None) → JavaScriptResult

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.

async load_url(url: str) → Future

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

Note: On Android, this method will return immediately.

Parameters:

url – The URL to load.

property on_navigation_starting

A handler that will be invoked when the TaWebView is requesting permission to navigate or redirect to a different URI.

Returns:

The function callable that is called by this navigation event.

The handler will receive following arguments:

Parameters:

  • widget (TaWebView) – The TaWebView instance

  • url (str) – The URL to be navigated to

  • event (object) – The native Event object

property on_resource_requested

The handler to invoke when the webview starts loading resources.

Returns:

The function callable that is called when the webview starts loading resources.

property on_webview_load: OnWebViewLoadHandler

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: str, content: str) → None

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 – A URL which will be returned by the url property, and used to resolve any relative URLs in the content.

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