| # 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`<br/> |
| Unsupported. Missing upstream API. |
| (https://github.com/MicrosoftEdge/WebView2Feedback/issues/120). |
| |
| * `StatusTextListener`<br/> |
| Unsupported. Conceptually obsolete. |
| |
| * `VisibilityWindowListener.hide`<br/> |
| Unsupported. Conceptually obsolete. |
| |
| * `ProgressListener.changed`<br/> |
| Unsupported. Missing upstream API. |
| |
| * `ProgressListener.completed`<br/> |
| 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`<br/> |
| 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`<br/> |
| Fires for the top document only. Doesn't fire when using `setText()` (TODO). |
| |
| * `KeyListener`, `MouseListener`<br/> |
| Unsupported. Missing upstream API. |
| (https://github.com/MicrosoftEdge/WebView2Feedback/issues/112). |
| Emulation with script callbacks is possible. |
| |
| * `evaluate(String script, boolean trusted)`<br/> |
| The parameter `trusted` is ignored. Everything runs in the same security |
| context scoped to a given user directory. |
| |
| * `execute(String script)`<br/> |
| Execution is always asynchronous. You can't observe evaluation effects |
| immediately after the `execute()` call. See `evaluate()` for synchronous |
| script evaluation. |
| |
| * `getText()`<br/> |
| 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.<br/> |
| _Note_: Implemented as `evaluate("return document.documentElement.outerHTML")`. |
| |
| * `setText()`<br/> |
| This method uses `data:` URLs internally (WebView2 implementation detail) |
| and these URLs might appear in the `LocationEvent.url` field. |
| |
| * `getCookie()`, `setCookie()`<br/> |
| 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)`<br/> |
| The parameters `headers` and `postData` require Edge 88 or later |
| (currently in Beta). |
| |
| * `close()`<br/> |
| 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. |