WebView2 Support for SWT

WebView2 is a runtime component that provides an embeddable version of Microsoft Edge.

WebView2 component is available from multiple sources:

• A stand-alone auto-updating runtime component with a choice of web and offline installers. (https://developer.microsoft.com/en-us/microsoft-edge/webview2/)

• A fixed-version archive with all the necessary files that can be bundled with the application. (Same link as above).

• Beta/Dev/Canary version of the Edge browser. (https://www.microsoftedgeinsider.com/en-us/download). This isn't suitable for production use, but might be necessary to test new pre-release features.

  Note: Stable Edge browser installations don't provide a WebView2 component.

See also: https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution.

Using WebView2

There are no extra dependencies beyond the WebView2 runtime itself.

On Windows, the default Browser backend is Internet Explorer. To use the WebView2 backend, pass the SWT.EDGE style flag when creating a Browser instance. Alternatively, set the system property org.eclipse.swt.browser.DefaultType to edge to globally change the default. (Non-Windows platforms will ignore this value).

Note: If WebView2 backend is requested but the runtime isn't found, the Browser will automatically fall back to the Internet Explorer backend.

Browser Directory

WebView2 backend will automatically locate runtimes and Edge installations. The path to the Edge binary directory can also be set manually using the org.eclipse.swt.browser.EdgeDir system property. This is also required when bundling fixed-version WebView2 binaries.

User Directory

WebView creates a user data directory to stores caches and persistent data like cookies and localStorage. All WebView2 instances in an application and all instances of the same application share this directory.

The default user directory location is %LOCALAPPDATA%\<AppName>\WebView2, where <AppName> is defined with Display.setAppName(). This location can be overridden on a per-process basis by setting the org.eclipse.swt.browser.EdgeDataDir system property.

See also: https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/userdatafolder

Other System Properties

The property org.eclipse.swt.browser.EdgeArgs defines command line arguments to be passed directly to the Chromium process. For a list of available arguments (unofficial) see https://peter.sh/experiments/chromium-command-line-switches/.

The property org.eclipse.swt.browser.EdgeLanguage is a language or language+country code that defines the browser UI language and preferred language for HTTP requests (Accept-Languages header). Example values: en, ja, en-GB, de-AT.

Note: All of the properties described above must be set before the first instance of the Browser with SWT.EDGE style is created.

Informational property org.eclipse.swt.browser.EdgeVersion contains the version of the browser currently in use.

Limitation and Caveats

Due to API mismatch between SWT and WebView2, some features are limited or not available.

• AuthenticationListener
  Unsupported. Missing upstream API. (https://github.com/MicrosoftEdge/WebView2Feedback/issues/120).

• StatusTextListener
  Unsupported. Conceptually obsolete.

• VisibilityWindowListener.hide
  Unsupported. Conceptually obsolete.

• ProgressListener.changed
  Unsupported. Missing upstream API.

• ProgressListener.completed
  Fires for the top level document only. On Edge version 88 and later it matches the DOMContentLoaded event, on earlier versions it matches the load event.

• LocationListener.changing, OpenWindowListener.open
  These events may return values and have to run synchronously. Calling evaluate() and getText() from their handlers is impossible and will throw an exception. (This can only be fixed by exposing the asynchronous evaluate() method).

• LocationListener.changed
  Fires for the top document only. Doesn't fire when using setText() (TODO).

• KeyListener, MouseListener
  Unsupported. Missing upstream API. (https://github.com/MicrosoftEdge/WebView2Feedback/issues/112). Emulation with script callbacks is possible.

• evaluate(String script, boolean trusted)
  The parameter trusted is ignored. Everything runs in the same security context scoped to a given user directory.

• execute(String script)
  Execution is always asynchronous. You can't observe evaluation effects immediately after the execute() call. See evaluate() for synchronous script evaluation.

• getText()
  Returns the live contents of HTML document as seen by the browser. This can differ from what was set with setText() due to browser processing and script execution.
  Note: Implemented as evaluate("return document.documentElement.outerHTML").

• setText()
  This method uses data: URLs internally (WebView2 implementation detail) and these URLs might appear in the LocationEvent.url field.

• getCookie(), setCookie()
  Unsupported. WebView doesn't have a global cookie manager. Cookie access is provided by individual browser views and required Browser API additions.

• setUrl(String url, String postData, String[] headers)
  The parameters headers and postData require Edge 88 or later (currently in Beta).

• close()
  Unsupported. Missing upstream API.

Known issues in WebView2

• When using OpenWindowListener, calling window.open() with an invalid URL might glitch the WebView. (https://github.com/MicrosoftEdge/WebView2Feedback/issues/762).

Potential API additions

Here are some potentially useful WebView2 features that could be exposed through API additions, Widget.setData or system properties:

• An option to delete the user data directory on exit.
• Getting and setting page zoom.
• Options to disable: page zoom, dev tools, built-in context menus, built-in error pages, microphone, camera, geolocation, notifications, sensors, clipboard access.
• An option to provide own script dialogs (alert/confirm/prompt).
• Window.postMessage() communication as a clean, asynchronous alternative to BrowserFunction.
• Access to request/response headers and body.