A frameless desktop window whose page is HTML: a WebView2 window on Windows and a WebKitGTK window on Linux. The page draws everything, including its own background. Where the platform can, the window itself is see-through, so the page can be a transparent layer over the desktop.
The library is meant to be used as a submodule. The host application:
- calls
setApplicationNameandinitializeWindowingat startup, andsetApplicationIconif it has a PNG icon to show, - subclasses
WebViewWindow, overridinghtml()(ordevUrl()) andtitle(), - defines
showErrorfor each platform it runs on, the one desktop function the library leaves to the host. Theexamples/Host.*files have the Windows, Linux and macOS versions.
- A window is hidden until its page reports that it's ready, so it never shows as an empty frame. A
showorpresentthat comes before then takes effect once the page is ready. The page reports it by posting{id, method: 'ready', args: []}to the host, once it has subscribed to the events it needs. Until then, host events wait for it. - Events queue until the page is ready, and replies from a page that has since been reloaded are dropped.
- If the page doesn't report ready within
WindowOptions::startupTimeout(10 seconds by default) on Windows, macOS or Linux, or the web view fails, the window callsonWebViewFailure. The default shows the error and closes the window. A page can report its own failure by posting{id, method: 'frontendError', args: [message]}.reload()recreates the web view and loads the page again. WindowOptions::webViewDataFoldersets where WebView2 keeps its profile. Empty means a folder beside the executable.hidefrees the window's web view after two minutes, unless the window is shown again first. The nextshoworpresentopens the window again.- When the user closes a window,
allowClosedecides. If it returns true, the window is destroyed. A window that should stay reusable returns false and hides itself, as it would throughhide. WindowOptions::resizeEdgesdraws strips along the window's edges, after each page load, and a press on one starts a resize from that edge. The page doesn't need to draw them. It applies whenresizableis set and the window isn't autosize.WindowOptions::clickThroughmakes the window pass mouse clicks to whatever is beneath it, so the page gets no pointer input. It's fixed when the window opens. On Windows it setsWS_EX_TRANSPARENT; on Linux it sets an empty input shape on the GTK window.WebViewWindow::setInputRegionmakes only some rectangles of the window take the pointer; pointer actions elsewhere pass through to the windows beneath. The rectangles are in the window's units, from its top left, and an empty list lets everything through. The page sends it, so a page can take the pointer over just the parts it draws. Windows answers the hit test, and Linux sets the GTK input shape. macOS doesn't take a region yet, so the whole window takes the pointer there.
- When a page asks for the microphone, camera or notifications, the host's
onPermissionRequestanswers. Return true to allow, false to deny, or nothing to leave the platform's default: WebKitGTK denies the request, and WebView2 asks the user. The answer comes fromdecidePermission, which the platform calls with the page's address. - On Linux, notifications are decided once for the window's own page origin (its
devUrl) when the window opens, since WebKitGTK otherwise denies them. A page at another origin is asked when it asks. - Other permission kinds reach
onPermissionRequestasPagePermission::Otheron Windows and are left to the platform on Linux.
include/: the public headers.WebViewWindow.his the window;Messages.his the page-to-host message dispatch.src/: the parts shared by both platforms.platform/windows/: the Win32 window, WebView2 callbacks, and DirectComposition for see-through windows.platform/linux/: the GTK and WebKitGTK window. GTK is loaded at runtime, so only the headers inthird_party/gtkare needed.platform/macos/: the AppKit and WebKit window, in Objective-C++. See Status.third_party/: WebView2 headers and loader, GTK headers, and nlohmann/json.
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/mingw-w64.cmake
cmake --build build
The Windows build uses MinGW-w64. The example is built with WEBVIEW_WINDOW_BUILD_EXAMPLE (on by default). Set it to OFF
when the library is used as a submodule. The WebView2 runtime must be installed on the machine that runs the program.
Every feature needs at least one test that runs on each platform: Windows, Linux and macOS. A test that doesn't depend on the platform counts for all three, so one such test is enough. A feature with no passing test on a platform is not finished there.
- A stub counts as a feature. It needs either a real implementation, or a test that checks the result the header documents (for example,
that
updateTrayIconreturnsfalsewhere it isn't implemented). - A test counts only when a script in
tests/or a CI job runs it on that platform. A test that is written but never run doesn't count. TODO.mdlists the features that have no test on each platform.
- Windows: built and run with the example. The permission hook compiles with MinGW but hasn't been run on Windows yet. The
click-through test (
tests/windows_click_through_test.ps1) is in.github/workflows/windows-permissions.yml; it hasn't run yet. - Linux: built and run with the example.
tests/linux_example_test.sh,tests/linux_permission_test.shandtests/linux_click_through_test.shandtests/linux_input_region_test.shcheck it. The click-through and input-region tests pass on X11. - macOS: the window, its WKWebView, and the example's features are implemented in
platform/macos/. The.github/workflows/macos.ymlworkflow builds the library and example on a macOS runner. Thetests/macos_*.shscripts check the window's behaviour on a Mac; CI only builds them.