WebView

macOS

GTK+

Windows

iOS

Android

Django

y

y

y

y

y

y

The Web View widget is used for displaying an embedded browser window within an application.

Both sites served by a web server and local content can be displayed. Due to security restrictions in the macOS backend WKWebView, local content on macOS can only be loaded from a single directory, relative to the base URL, and not from an absolute “file://” URL. As a workaround, it is possible to use a lightweight webserver instead.

../../../_images/WebView.jpeg

Usage

import toga

web = toga.WebView(url='https://google.com')

Debugging

If you need to debug the HTML, JavaScript or CSS content of a view, you may want to use the “inspect element” feature of the WebView. This is not be turned on by default on some platforms. To enable WebView debugging:

  • macOS

    Run the following at the terminal:

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

    substituting com.example.appname with the bundle ID for your app.

Reference

class toga.widgets.webview.WebView(id=None, style=None, factory=None, url=None, user_agent=None, on_key_down=None, on_webview_load=None)

A widget to display and open html content.

Parameters
  • id (str) – An identifier for this widget.

  • style (Style) – An optional style object. If no style is provided then a new one will be created for the widget.

  • factory (module) – A python module that is capable to return a implementation of this class with the same name. (optional & normally not needed)

  • url (str) – The URL to start with.

  • user_agent (str) – The user agent for the web view.

  • on_key_down (callable) – The callback method for when a key is pressed within the web view

  • on_webview_load (callable) – The callback method for when the webview loads (or reloads).

MIN_HEIGHT = 100
MIN_WIDTH = 100
add(*children)

Add nodes as children of this one. If a node already has a different parent, it will be moved over. This does nothing if a node already is a child of this node.

Parameters

children – Nodes to add as children of this node.

Raises

ValueError – If this node is a leaf, and cannot have children.

property app

The App to which this widget belongs. On setting the app we also iterate over all children of this widget and set them to the same app.

Returns

The toga.App to which this widget belongs.

Raises

ValueError – If the widget is already associated with another app.

property can_have_children

Determine if the node can have children.

This does not resolve whether there actually are any children; it only confirms whether children are theoretically allowed.

property children

The children of this node. This always returns a list, even if the node is a leaf and cannot have children.

Returns

A list of the children for this widget.

property dom

The current DOM

Returns

The current DOM as a str.

property enabled
async evaluate_javascript(javascript)

Evaluate a JavaScript expression, returning the result.

This is an asynchronous operation. The method will complete when the return value is available.

Parameters

javascript (str) – The javascript expression to evaluate.

focus()
property id

The node identifier. This id can be used to target styling directives

Returns

The widgets identifier as a str.

insert(index, child)

Insert a node as a child of this one. If the node already has a different parent, it will be moved over. This does nothing if the node already is a child of this node.

Parameters
  • index – Position of child node.

  • child – A node to insert as a child of this node.

Raises

ValueError – If this node is a leaf, and cannot have children.

invoke_javascript(javascript)

Invoke a JavaScript expression.

The result (if any) of the javascript is ignored.

No guarantee is provided that the javascript has completed execution when `invoke()` returns

Parameters

javascript (str) – The javascript expression to evaluate.

property on_key_down

The handler to invoke when the button is pressed.

Returns

The function callable that is called on button press.

property on_webview_load

The handler to invoke when the webview finishes loading pressed.

Returns

The function callable that is called when the webview finished loading.

property parent

The parent of this node.

Returns

The parent of this node. Returns None if this node is the root node.

refresh()

Refresh the layout and appearance of the tree this node is contained in.

refresh_sublayouts()
remove(*children)

Remove child nodes of this node. This does nothing if a given node is not a child of this node.

Parameters

children – Child nodes to remove.

Raises

ValueError – If this node is a leaf, and cannot have children.

property root

The root of the tree containing this node.

Returns

The root node. Returns self if this node is the root node.

set_content(root_url, content)

Set the content of the web view.

Parameters
  • root_url (str) – The URL.

  • content (str) – The new content.

Returns:

property url

The current URL

Returns

The current URL as a str.

property user_agent

The user agent for the web view as a str.

Returns

The user agent as a str.

property window

The Window to which this widget belongs. On setting the window, we automatically update all children of this widget to belong to the same window.

Returns

The toga.Window to which the widget belongs.