From 1872d9c5c4c36517daea5045f8919a93520bc20d Mon Sep 17 00:00:00 2001 From: Jon Date: Fri, 13 Nov 2026 09:19:21 +0000 Subject: [PATCH] Add WindowOptions::clickThrough, so a window passes mouse clicks through A window opened with clickThrough never takes pointer input: clicks reach whatever is beneath it. It's set when the window opens. On Windows it adds WS_EX_TRANSPARENT to the extended style. On Linux it sets an empty input shape on the GTK window, with the cairo region loaded at runtime like the rest of GTK. The example takes --click-through. The new tests check that the window under the pointer is the window beneath the example when it's set, and the example's own window when it isn't: tests/linux_click_through_test.sh on X11, and tests/windows_click_through_test.ps1, which the Windows CI workflow runs. --- .github/workflows/windows-permissions.yml | 4 ++ README.md | 8 ++- examples/main.cpp | 5 ++ include/WebViewWindow.h | 3 + platform/linux/WebViewWindow.cpp | 20 +++++++ platform/windows/WebViewWindow.cpp | 4 ++ tests/linux_click_through_test.sh | 68 +++++++++++++++++++++++ tests/windows_click_through_test.ps1 | 61 ++++++++++++++++++++ tests/windows_common.ps1 | 20 +++++++ 9 files changed, 191 insertions(+), 2 deletions(-) create mode 100644 tests/linux_click_through_test.sh create mode 100644 tests/windows_click_through_test.ps1 diff --git a/.github/workflows/windows-permissions.yml b/.github/workflows/windows-permissions.yml index 66d823c..71ff5da 100644 --- a/.github/workflows/windows-permissions.yml +++ b/.github/workflows/windows-permissions.yml @@ -36,3 +36,7 @@ jobs: - name: Run the download test shell: pwsh run: ./tests/windows_download_test.ps1 -BuildDir build + + - name: Run the click-through test + shell: pwsh + run: ./tests/windows_click_through_test.ps1 -BuildDir build diff --git a/README.md b/README.md index 75044e7..74c911b 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,8 @@ The library is meant to be used as a submodule. The host application: reusable returns false and hides itself, as it would through `hide`. - `WindowOptions::resizeEdges` draws 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 when `resizable` is set and the window isn't autosize. +- `WindowOptions::clickThrough` makes 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 sets `WS_EX_TRANSPARENT`; on Linux it sets an empty input shape on the GTK window. ## Permissions @@ -56,8 +58,10 @@ when the library is used as a submodule. The WebView2 runtime must be installed ## Status -- Windows: built and run with the example. The permission hook compiles with MinGW but hasn't been run on Windows yet. -- Linux: built and run with the example. `tests/linux_example_test.sh` and `tests/linux_permission_test.sh` check it. +- 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.sh` and + `tests/linux_click_through_test.sh` check it. The click-through test passes on X11. - macOS: the window, its WKWebView, and the example's features are implemented in `platform/macos/`. The `.github/workflows/macos.yml` workflow builds the library and example on a macOS runner. The `tests/macos_*.sh` scripts check the window's behaviour on a Mac; CI only builds them. diff --git a/examples/main.cpp b/examples/main.cpp index 8a58d01..deec9f4 100644 --- a/examples/main.cpp +++ b/examples/main.cpp @@ -36,6 +36,7 @@ // --min-size the smallest size the user can resize the window to // --startup-timeout seconds the page has to report ready before the window fails (0 for no limit) // --no-ready the built-in page never reports ready, so the window fails at the startup timeout +// --click-through the window passes mouse clicks through to the windows beneath it // The state is one line: "visible=<0|1> open=<0|1> frame=,,, area=,,,". The frame is the // window's rectangle on the screen in pixels, or "frame=none" when it has no native window. The area is the work area of the // monitor the window is on, or "area=none". @@ -81,6 +82,7 @@ struct Settings { bool autosize = false; bool invisible = false; bool noReady = false; + bool clickThrough = false; int minWidth = 0; int minHeight = 0; std::chrono::seconds startupTimeout = std::chrono::seconds(30); @@ -177,6 +179,7 @@ class ExampleWindow : public WebViewWindow { options.skipTaskbar = settings.skipTaskbar; options.utility = settings.utility; options.transparent = !settings.opaque; + options.clickThrough = settings.clickThrough; options.titleBar = !settings.noTitleBar; options.resizable = !settings.notResizable; options.resizeEdges = settings.resizeEdges; @@ -272,6 +275,8 @@ bool parseSettings(int argc, char** argv, Settings& settings) { settings.utility = true; } else if (arg == "--opaque") { settings.opaque = true; + } else if (arg == "--click-through") { + settings.clickThrough = true; } else if (arg == "--clear-page") { settings.clearPage = true; } else if (arg == "--no-titlebar") { diff --git a/include/WebViewWindow.h b/include/WebViewWindow.h index c4bebcd..447c98f 100644 --- a/include/WebViewWindow.h +++ b/include/WebViewWindow.h @@ -60,6 +60,9 @@ struct WindowOptions { // The window's background is see-through, where the platform can show the desktop through it. Nothing is drawn behind the // page, so the page fills whatever it wants drawn. bool transparent = true; + // The window never takes mouse clicks: they pass through to whatever is beneath it. The page gets no input. It's fixed when the + // window opens, so it suits an overlay that's only ever seen, not used. + bool clickThrough = false; // The page's hardware acceleration policy. Unset leaves WebKit's default in place. std::optional hardwareAcceleration; // The folder WebView2 keeps its profile and caches in. Empty means a folder beside the executable. diff --git a/platform/linux/WebViewWindow.cpp b/platform/linux/WebViewWindow.cpp index 0233208..efe17ef 100644 --- a/platform/linux/WebViewWindow.cpp +++ b/platform/linux/WebViewWindow.cpp @@ -82,6 +82,11 @@ struct GtkApi { void (*widget_show)(GtkWidget*) = nullptr; void (*widget_show_all)(GtkWidget*) = nullptr; GdkWindow* (*widget_get_window)(GtkWidget*) = nullptr; + void (*widget_realize)(GtkWidget*) = nullptr; + // The input shape takes a cairo region, which the cairo library makes. Both come from the libraries opened at start. + void (*widget_input_shape_combine_region)(GtkWidget*, void*) = nullptr; + void* (*cairo_region_create)() = nullptr; + void (*cairo_region_destroy)(void*) = nullptr; guint32 (*x11_server_time)(GdkWindow*) = nullptr; void (*window_begin_resize_drag)(GtkWindow*, GdkWindowEdge, gint, gint, gint, guint32) = nullptr; void (*window_begin_move_drag)(GtkWindow*, gint, gint, gint, guint32) = nullptr; @@ -214,6 +219,13 @@ GtkApi loadApi() { bind(api.widget_show, library, "gtk_widget_show"); bind(api.widget_show_all, library, "gtk_widget_show_all"); bind(api.widget_get_window, library, "gtk_widget_get_window"); + bind(api.widget_realize, library, "gtk_widget_realize"); + bind(api.widget_input_shape_combine_region, library, "gtk_widget_input_shape_combine_region"); + // Cairo is the library GTK draws with, so it's there whenever GTK is. It's opened here for the one region the input shape needs. + if (void* cairo = dlopen("libcairo.so.2", RTLD_LAZY | RTLD_LOCAL)) { + bind(api.cairo_region_create, cairo, "cairo_region_create"); + bind(api.cairo_region_destroy, cairo, "cairo_region_destroy"); + } // Only on X11. Without it the focus request carries no time, and the window manager may refuse it. api.x11_server_time = reinterpret_cast(dlsym(library, "gdk_x11_get_server_time")); bind(api.widget_hide, library, "gtk_widget_hide"); @@ -513,6 +525,14 @@ void WebViewWindow::platformOpen() { const RgbaColor clear{0, 0, 0, 0}; gtk.web_view_set_background_color(native.view, &clear); } + if (options_.clickThrough && gtk.cairo_region_create) { + // An empty input shape means the window takes no pointer input, so clicks reach whatever is beneath it. The shape is set once + // the widget is realized, and GTK copies the region, so it's released straight after. + gtk.widget_realize(native.window); + void* empty = gtk.cairo_region_create(); + gtk.widget_input_shape_combine_region(native.window, empty); + gtk.cairo_region_destroy(empty); + } gtk.container_add(reinterpret_cast(native.window), reinterpret_cast(native.view)); gtk.g_signal_connect_data(native.view, "web-process-crashed", reinterpret_cast(onWebProcessCrashed), this, nullptr, static_cast(0)); diff --git a/platform/windows/WebViewWindow.cpp b/platform/windows/WebViewWindow.cpp index 373ebfc..8f4ecd4 100644 --- a/platform/windows/WebViewWindow.cpp +++ b/platform/windows/WebViewWindow.cpp @@ -844,6 +844,10 @@ void WebViewWindow::platformOpen() { // The window has no surface of its own, so what the composition draws over it is all that shows. exStyle |= WS_EX_NOREDIRECTIONBITMAP; } + if (options.clickThrough) { + // Hit testing skips the window, so mouse clicks reach whatever is beneath it. + exStyle |= WS_EX_TRANSPARENT; + } native_.reset(new NativeWindow); NativeWindow* native = native_.get(); diff --git a/tests/linux_click_through_test.sh b/tests/linux_click_through_test.sh new file mode 100644 index 0000000..34f297a --- /dev/null +++ b/tests/linux_click_through_test.sh @@ -0,0 +1,68 @@ +#!/usr/bin/env bash +# Checks that a window opened with clickThrough passes the pointer through to the windows beneath it. The pointer is moved over the +# middle of the example's window, and the window the X server reports under it must not be the example's. The control runs the same +# check without --click-through, where the example's window must be the one under the pointer. Every wait is at most 10 seconds. +# +# The check uses xdotool, so the test needs an X display. +# +# Usage: tests/linux_click_through_test.sh [build-dir] +set -euo pipefail + +source "$(dirname "$0")/linux_common.sh" + +# The window the X server reports under the pointer, as a hexadecimal id, or "none" when the query gives nothing. +window_under_pointer() { + local px="$1" py="$2" id + xdotool mousemove --sync "$px" "$py" + id="$(xdotool getmouselocation --shell | sed -n 's/^WINDOW=//p')" + echo "${id:-none}" +} + +# The example's own window, by its title. Empty when it isn't on screen. +example_window_id() { + xdotool search --onlyvisible --name "^${title}$" 2>/dev/null | head -n 1 +} + +# The pointer's target: the middle of the example's frame, from the example's report. +pointer_target() { + local x y w h + IFS=, read -r x y w h <<< "$(frame_now)" + echo "$((x + w / 2)) $((y + h / 2))" +} + +# Both runs use one build: the given build directory, or the one start_example makes in the work folder. +given_build="${1:-}" +build_dir="${given_build:-$work/build}" + +start_example "$given_build" --click-through + +if wait_for_line_after 0 '^loaded$'; then pass "page loaded"; else fail "page never reported loaded"; fi +if wait_for_window shown; then pass "window is shown"; else fail "window never appeared"; fi + +read -r px py <<< "$(pointer_target)" +own="$(example_window_id)" +under="$(window_under_pointer "$px" "$py")" +if [[ -n "$own" && "$under" != "none" && "$under" != "$own" ]]; then + pass "with --click-through, the pointer over the window reaches the window beneath it ($under, not $own)" +else + fail "with --click-through, the pointer over the window reached the example's window: under=$under own=$own" +fi +stop_example + +# The control: the same window without clickThrough takes the pointer itself. +start_example "$build_dir" + +if wait_for_line_after 0 '^loaded$'; then pass "control page loaded"; else fail "control page never reported loaded"; fi +if wait_for_window shown; then pass "control window is shown"; else fail "control window never appeared"; fi + +read -r px py <<< "$(pointer_target)" +own="$(example_window_id)" +under="$(window_under_pointer "$px" "$py")" +if [[ -n "$own" && "$under" == "$own" ]]; then + pass "without --click-through, the example's window is under the pointer" +else + fail "without --click-through, the window under the pointer is $under, not the example's $own" +fi +stop_example + +finish diff --git a/tests/windows_click_through_test.ps1 b/tests/windows_click_through_test.ps1 new file mode 100644 index 0000000..2255a9f --- /dev/null +++ b/tests/windows_click_through_test.ps1 @@ -0,0 +1,61 @@ +# Checks that a window opened with clickThrough passes the pointer through to the windows beneath it. The pointer is moved over the +# middle of the example's window, and the top-level window that hit testing finds there must not be the example's. The control runs +# the same check without --click-through, where the example's window must be the one under the pointer. Every wait is at most 10 +# seconds. +# +# The pointer is moved with SetCursorPos, so the test needs an interactive desktop. +# +# Usage: tests/windows_click_through_test.ps1 [-BuildDir ] +param([string]$BuildDir = "") + +. "$PSScriptRoot\windows_common.ps1" + +# The pointer's target: the middle of the example's frame, from its report. +function Get-PointerTarget { + $x, $y, $w, $h = Split-Rect (Get-FrameNow) + return @(($x + [math]::Floor($w / 2)), ($y + [math]::Floor($h / 2))) +} + +try { + # Both runs use one build: the given build directory, or the one Start-Example makes in the work folder. + $build = if ($BuildDir) { $BuildDir } else { Join-Path $script:work "build" } + + Start-Example -BuildDir $BuildDir -Arguments @("--click-through") + + if (Wait-ForLineAfter 0 '^loaded$') { Pass "page loaded" } else { Fail "page never reported loaded" } + if (Wait-ForWindow "shown") { Pass "window is shown" } else { Fail "window never appeared" } + + $px, $py = Get-PointerTarget + [WebViewTestNative]::MovePointer($px, $py) + Start-Sleep -Milliseconds 200 + $own = Get-ExampleWindow + $under = [WebViewTestNative]::TopLevelAt($px, $py) + if (($under -ne [IntPtr]::Zero) -and (-not $under.Equals($own))) { + Pass "with --click-through, the pointer over the window reaches the window beneath it" + } else { + Fail "with --click-through, the pointer over the window reached the example's window: under=$under own=$own" + } + Stop-Example + + # The control: the same window without clickThrough takes the pointer itself. + Start-Example -BuildDir $build + + if (Wait-ForLineAfter 0 '^loaded$') { Pass "control page loaded" } else { Fail "control page never reported loaded" } + if (Wait-ForWindow "shown") { Pass "control window is shown" } else { Fail "control window never appeared" } + + $px, $py = Get-PointerTarget + [WebViewTestNative]::MovePointer($px, $py) + Start-Sleep -Milliseconds 200 + $own = Get-ExampleWindow + $under = [WebViewTestNative]::TopLevelAt($px, $py) + if (($own -ne [IntPtr]::Zero) -and $under.Equals($own)) { + Pass "without --click-through, the example's window is under the pointer" + } else { + Fail "without --click-through, the window under the pointer is $under, not the example's $own" + } + Stop-Example +} finally { + Remove-Harness +} + +Finish diff --git a/tests/windows_common.ps1 b/tests/windows_common.ps1 index 2bf0cd3..2855fb2 100644 --- a/tests/windows_common.ps1 +++ b/tests/windows_common.ps1 @@ -47,6 +47,16 @@ public static class WebViewTestNative { private static extern bool SetCursorPos(int x, int y); [DllImport("user32.dll")] private static extern void mouse_event(uint flags, uint dx, uint dy, uint data, UIntPtr extraInfo); + [DllImport("user32.dll")] + private static extern IntPtr WindowFromPoint(POINT point); + [DllImport("user32.dll")] + private static extern IntPtr GetAncestor(IntPtr window, uint flags); + + [StructLayout(LayoutKind.Sequential)] + private struct POINT { + public int X; + public int Y; + } // The top-level window of a process with the title, shown or hidden, or IntPtr.Zero. public static IntPtr FindWindow(uint processId, string title) { @@ -83,6 +93,16 @@ public static class WebViewTestNative { SetCursorPos(x, y); } + // The top-level window that hit testing finds at the screen point, skipping windows that are click-through, or IntPtr.Zero. + public static IntPtr TopLevelAt(int x, int y) { + const uint gaRoot = 2; + POINT point; + point.X = x; + point.Y = y; + IntPtr window = WindowFromPoint(point); + return window == IntPtr.Zero ? IntPtr.Zero : GetAncestor(window, gaRoot); + } + // The left button, pressed or released where the pointer is. public static void SetLeftButton(bool down) { const uint leftDown = 0x0002;