WebView#

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.

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.
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 the provided widgets as children of this widget.

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.

Raises ValueError if this widget cannot have children.

Parameters:: children – The widgets to add as children of this widget.

property app#

The App to which this widget belongs.

When setting the app for a widget, all children of this widget will be recursively assigned to the same app.

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
Return type:: str

property enabled#: Is the widget currently enabled? i.e., can the user interact with the widget?

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()#: Set this widget to have the current input focus.

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

insert(index, child)#

Insert a widget as a child of this widget.

If the node already has a parent, ownership of the widget will be transferred.

Raises ValueError if this node cannot have children.

Parameters:

index – The position in the list of children where the new widget should be added.
child – The child to insert as a child of this node.

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 that is called on button press.
Return type:: callable

property on_webview_load#

The handler to invoke when the webview finishes loading.

Returns:: The function that is called when the webview finishes loading.
Return type:: callable

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 the provided widgets as children of this node.

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

Raises ValueError if this node is a leaf, and cannot have children.

Parameters:: children – The child nodes to remove.

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

property tab_index#: The position of the widget in the focus chain for the window.

property url#

The current URL.

Returns:: The current URL
Return type:: str

property user_agent#

The user agent for the web view as a str.

Returns:: The user agent
Return type:: str

property window#

The window to which this widget belongs.

When setting the window for a widget, all children of this widget will be recursively assigned to the same window.