Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,8 @@ Chapter numbers refer to `docs/architecture/NN-*.md`.
- Tracking never moves the pointer: detached views (`t.viewDetached`); the pointer comes to the view
on a mouse move. Never poll the Java Access Bridge at a fixed rate (reads follow bridge events,
a window switch or a backed-off retry); load only Authenticode-signed bridge DLLs.
- Shell input panels (emoji picker, Win+V) need nothing in a Native session: DWM draws its pointer
- Shell input panels (emoji picker, Win+V) and the taskbar keyboard layout menu (#569,
`shell_panel.h`) need nothing in a Native session: DWM draws its pointer
above them. A Wind session shows the real pointer through the cursor lens while one is open, frozen
by a 1 px clip that Wind moves with the view (#492); keep that freeze hidden from the lock tell.
Never use hook-thread view writes for it.
Expand Down
14 changes: 9 additions & 5 deletions docs/architecture/07-cursor.md
Original file line number Diff line number Diff line change
Expand Up @@ -420,15 +420,19 @@ turns held pan keys into a view delta in screen space, so the feel does not chan
- While panning, KeyPan owns the view ahead of caret events. The delta is clamped to the monitor
and the MPO wall. The pointer does not move; the next mouse move places it in the view.

## Shell input panels
## Shell input panels and the keyboard layout menu

The emoji picker, clipboard history and touch keyboard are composed above every window band, so
only the real pointer shows over them. A Native session needs nothing: DWM draws its pointer above
the panels and keeps it centred, so the hand moves the pointer directly.
only the real pointer shows over them. The taskbar keyboard layout menu (#569) behaves the same: it
sits in band 3 (`ZBID_IMMERSIVE_IHM`, the input panels' band). A Native session needs nothing: DWM
draws its pointer above the panels and keeps it centred, so the hand moves the pointer directly.

A Wind session (#283, ported back in #492) switches to the real pointer while a panel is open.
`FocusTracker::shellPanelOpen` follows `TextInputHost`'s `IME` window (UNCLOAKED = open, CLOAKED =
closed, a 250 ms re-check while open, a scan at start-up). `MapPointer` then freezes the pointer with
`FocusTracker::shellPanelOpen` follows two windows (`src/track/shell_panel.h`, tested):
`TextInputHost`'s `IME` window (open while uncloaked) and explorer's
`Shell_InputSwitchTopLevelWindow`, "Input Flyout" (open while visible and uncloaked; it shows and
hides). Cloak and show/hide hooks feed it, a close rescans for any other open panel, a 250 ms
re-check runs while one is open, and a scan runs at start-up. `MapPointer` then freezes the pointer with
a 1 px clip and moves it from raw mickeys at the learned desktop gain (Inspect's replay); the model
hides the sprite, restores the cursor set, turns the cursor lens style on (the public prime only if
no lens could be built) and moves the pin right after the view write (`ex.realPointer`), so DWM never
Expand Down
90 changes: 55 additions & 35 deletions src/track/focus_track.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
#include "caret_rect.h" // trim tall UIA caret rects (#337)
#include "java_bridge.h"
#include "java_bridge_util.h"
#include "shell_panel.h" // which shell windows sit above every band (#569)
#include <windows.h>
#include <objbase.h>
#include <oleacc.h>
Expand All @@ -28,51 +29,75 @@ static const UINT_PTR kCoalesceTimer = 1;
static FocusTracker* g_self = nullptr; // WinEvent callbacks have no context pointer
static UINT_PTR g_panelTimer = 0; // re-checks a panel marked open (tracker thread only)

// The shell's input panels (emoji picker, clipboard history, touch keyboard) are hosted by
// TextInputHost.exe and composed by the shell ABOVE every app window, so no band Wind can create
// covers them (#283, measured 2026-09-29). They never change as windows either: the only reliable
// signal is TextInputHost's "IME" window, uncloaked while a panel shows and cloaked when it closes.
// "IME" is a common class name (every GUI thread has one), so the owning process is checked too.
static bool IsShellPanelWindow(HWND h) {
wchar_t cls[16] = {};
if (!GetClassNameW(h, cls, 16) || wcscmp(cls, L"IME") != 0) return false;
// Shell surfaces composed ABOVE every window band, so no band Wind can create covers them: the
// input panels (TextInputHost's "IME" window, #283) and explorer's keyboard layout menu (#569).
// Which windows and when they count: shell_panel.h.
static ShellPanelKind ShellPanelKindOf(HWND h) {
wchar_t cls[64] = {};
if (!GetClassNameW(h, cls, 64)) return ShellPanelKind::None;
// Cheap class test first: the show/hide hook sees every window in the session.
if (wcscmp(cls, L"IME") != 0 && wcscmp(cls, L"Shell_InputSwitchTopLevelWindow") != 0)
return ShellPanelKind::None;
DWORD pid = 0; GetWindowThreadProcessId(h, &pid);
HANDLE p = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, FALSE, pid);
if (!p) return false;
if (!p) return ShellPanelKind::None;
wchar_t path[MAX_PATH]; DWORD n = MAX_PATH;
bool yes = false;
ShellPanelKind k = ShellPanelKind::None;
if (QueryFullProcessImageNameW(p, 0, path, &n)) {
const wchar_t* base = wcsrchr(path, L'\\');
yes = _wcsicmp(base ? base + 1 : path, L"TextInputHost.exe") == 0;
k = ClassifyShellPanel(cls, base ? base + 1 : path, GetAncestor(h, GA_ROOT) == h);
}
CloseHandle(p);
return yes;
return k;
}

static bool ShellPanelShowsNow(HWND h, ShellPanelKind k) {
if (k == ShellPanelKind::None || !IsWindow(h)) return false;
DWORD cloaked = 0;
if (FAILED(DwmGetWindowAttribute(h, DWMWA_CLOAKED, &cloaked, sizeof(cloaked)))) cloaked = 0;
return ShellPanelShowing(k, IsWindowVisible(h) != FALSE, cloaked != 0);
}

struct FocusTrackImpl {
// Tracker thread only (the cloak hook, the start-up scan and the timer all run there).
// Tracker thread only (the hooks, the start-up scan and the timer all run there).
static void SetPanel(bool open, HWND h) {
if (!g_self) return;
g_self->panelHwnd_.store(open ? h : nullptr);
if (g_self->panelOpen_.exchange(open) != open)
wind::Log(wind::LogLevel::Info, "track", "shell input panel %s", open ? "open" : "closed");
// A missed close (TextInputHost restarted, an event dropped) must not leave the real pointer
// on for good: a 250 ms timer re-checks the remembered window while it is marked open.
wind::Log(wind::LogLevel::Info, "track", "shell panel %s", open ? "open" : "closed");
// A missed close (TextInputHost or explorer restarted, an event dropped) must not leave the
// real pointer on for good: a 250 ms timer re-checks the remembered window while it is open.
if (open && !g_panelTimer) g_panelTimer = SetTimer(nullptr, 0, 250, nullptr);
if (!open && g_panelTimer) { KillTimer(nullptr, g_panelTimer); g_panelTimer = 0; }
}
// Finds any panel still showing (the switcher and an input panel can be open at once, and closing
// one must not drop the other). Runs only on a panel's close, the timer and start-up.
static void RescanPanels() {
HWND found = nullptr;
EnumWindows([](HWND h, LPARAM lp) -> BOOL {
if (!ShellPanelShowsNow(h, ShellPanelKindOf(h))) return TRUE;
*reinterpret_cast<HWND*>(lp) = h;
return FALSE;
}, reinterpret_cast<LPARAM>(&found));
SetPanel(found != nullptr, found);
}
static void CheckPanel() {
if (!g_self || !g_self->panelOpen_.load()) return;
HWND ph = static_cast<HWND>(g_self->panelHwnd_.load());
DWORD cloaked = 0;
if (!ph || !IsWindow(ph) ||
(SUCCEEDED(DwmGetWindowAttribute(ph, DWMWA_CLOAKED, &cloaked, sizeof(cloaked))) && cloaked))
SetPanel(false, nullptr);
if (!ph || !ShellPanelShowsNow(ph, ShellPanelKindOf(ph))) RescanPanels();
}
static void CALLBACK OnCloak(HWINEVENTHOOK, DWORD ev, HWND h, LONG obj, LONG, DWORD, DWORD) {
// Cloak and show/hide events. The input panel only cloaks; the input switcher shows and hides,
// so both ranges are hooked and the window's own state decides.
static void CALLBACK OnPanelEvent(HWINEVENTHOOK, DWORD ev, HWND h, LONG obj, LONG, DWORD, DWORD) {
if (!g_self || !h || obj != OBJID_WINDOW) return;
if (!IsShellPanelWindow(h)) return;
SetPanel(ev == EVENT_OBJECT_UNCLOAKED, h);
const ShellPanelKind k = ShellPanelKindOf(h);
if (k == ShellPanelKind::None) return;
const bool opening = ev == EVENT_OBJECT_UNCLOAKED || ev == EVENT_OBJECT_SHOW;
// The input panel's UNCLOAKED is trusted as is (the #492 behaviour); the switcher's SHOW is
// checked against its window state.
const bool trusted = k == ShellPanelKind::InputPanel && ev == EVENT_OBJECT_UNCLOAKED;
if (opening && (trusted || ShellPanelShowsNow(h, k))) SetPanel(true, h);
else if (!opening && g_self->panelOpen_.load()) RescanPanels();
}
static void CALLBACK OnWinEvent(HWINEVENTHOOK, DWORD ev, HWND, LONG obj, LONG, DWORD, DWORD) {
if (!g_self || !g_self->active_.load()) return;
Expand Down Expand Up @@ -425,7 +450,8 @@ struct FocusRun {
// LOCATIONCHANGE fires for every moving window and caret system-wide: installed only while the
// tracker is active (zoomed), never at 1x (#71). The 16 ms caret backstop likewise.
HWINEVENTHOOK h4 = nullptr;
HWINEVENTHOOK h5 = nullptr; // shell input panels (#283, #492): always on, it fires only on cloaking
HWINEVENTHOOK h5 = nullptr; // shell panels (#283, #492): always on, it fires only on cloaking
HWINEVENTHOOK h6 = nullptr; // keyboard layout menu (#569): always on, show/hide
UINT_PTR pollTimer = 0;
void retune(bool on) {
if (on && !h4)
Expand Down Expand Up @@ -824,16 +850,10 @@ void FocusRun::setUp() {
h1 = SetWinEventHook(EVENT_SYSTEM_FOREGROUND, EVENT_SYSTEM_FOREGROUND, nullptr, FocusTrackImpl::OnWinEvent, 0, 0, WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS);
h2 = SetWinEventHook(EVENT_SYSTEM_MENUPOPUPSTART, EVENT_SYSTEM_MENUPOPUPSTART, nullptr, FocusTrackImpl::OnWinEvent, 0, 0, WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS);
h3 = SetWinEventHook(EVENT_OBJECT_FOCUS, EVENT_OBJECT_FOCUS, nullptr, FocusTrackImpl::OnWinEvent, 0, 0, WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS);
h5 = SetWinEventHook(EVENT_OBJECT_CLOAKED, EVENT_OBJECT_UNCLOAKED, nullptr, FocusTrackImpl::OnCloak, 0, 0, WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS);
// A panel already open when we start raised its UNCLOAKED before the hook existed (review #284).
EnumWindows([](HWND h, LPARAM) -> BOOL {
DWORD cloaked = 1;
if (IsShellPanelWindow(h) && SUCCEEDED(DwmGetWindowAttribute(h, DWMWA_CLOAKED, &cloaked, sizeof(cloaked))) && !cloaked) {
FocusTrackImpl::SetPanel(true, h);
return FALSE;
}
return TRUE;
}, 0);
h5 = SetWinEventHook(EVENT_OBJECT_CLOAKED, EVENT_OBJECT_UNCLOAKED, nullptr, FocusTrackImpl::OnPanelEvent, 0, 0, WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS);
h6 = SetWinEventHook(EVENT_OBJECT_SHOW, EVENT_OBJECT_HIDE, nullptr, FocusTrackImpl::OnPanelEvent, 0, 0, WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS);
// A panel already open when we start raised its event before the hooks existed (review #284).
FocusTrackImpl::RescanPanels();
retune(active_.load()); // an activation that raced thread start-up is picked up here
}

Expand Down Expand Up @@ -882,7 +902,7 @@ void FocusRun::messageLoop(MSG& m) {
void FocusRun::tearDown() {
if (pollTimer) KillTimer(nullptr, pollTimer);
if (g_panelTimer) { KillTimer(nullptr, g_panelTimer); g_panelTimer = 0; }
for (HWINEVENTHOOK h : { h1, h2, h3, h4, h5 }) if (h) UnhookWinEvent(h);
for (HWINEVENTHOOK h : { h1, h2, h3, h4, h5, h6 }) if (h) UnhookWinEvent(h);
if (uia && fh) uia->RemoveFocusChangedEventHandler(fh);
if (fh) fh->Release();
focusLookup.reset();
Expand Down
3 changes: 2 additions & 1 deletion src/track/focus_track.h
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ class FocusTracker {
// bridge DLL is never loaded.
void setActive(bool on, bool wantCaret, bool wantFocus, bool wantJava, bool log);
TrackSnapshot snapshot() const { std::lock_guard<std::mutex> g(mu_); return snap_; }
// A shell input panel (emoji picker Win+., clipboard Win+V, touch keyboard) is open (#283, #492).
// A shell panel is open (#283, #492, #569): an input panel (emoji picker Win+., clipboard Win+V,
// touch keyboard) or the taskbar keyboard layout menu (explorer's input switcher). See shell_panel.h.
// Watched always, independent of setActive: a Wind (sprite) session shows the real pointer then.
bool shellPanelOpen() const { return panelOpen_.load(); }
private:
Expand Down
57 changes: 57 additions & 0 deletions src/track/shell_panel.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
// Copyright (c) 2026 Max Aubert. All rights reserved.
// Proprietary source-available software; see LICENSE. SPDX-License-Identifier: LicenseRef-Wind-Proprietary
#pragma once
// Which top-level windows are shell surfaces composed ABOVE every window band Wind can create
// (#283, #492, #569). While one shows, the sprite cursor of a Wind session goes under it, so the
// session shows the real pointer instead. Pure: no <windows.h>, tested in tests/test_shell_panel.cpp.
//
// Measured with a WinEvent probe (GetWindowBand, DWMWA_CLOAKED):
// - Input panels (emoji Win+., clipboard Win+V, touch keyboard), 2026-09-29: TextInputHost.exe's
// "IME" window, uncloaked while a panel shows. "IME" is a common class (every GUI thread has
// one), so the process is checked too. The window is never shown or hidden, only cloaked.
// - The taskbar keyboard layout menu ("Input Flyout"), 2026-11-15 on 26300: explorer.exe's
// "Shell_InputSwitchTopLevelWindow", band 3 (ZBID_IMMERSIVE_IHM, the input panels' family),
// SHOWN on open and moved into place; it takes the foreground. A fullscreen
// "Shell_InputSwitchDismissOverlay" shows with it and is not needed for the test.
namespace wind {

enum class ShellPanelKind { None, InputPanel, InputSwitcher };

inline bool ShellPanelEqI(const wchar_t* a, const wchar_t* b) {
if (!a || !b) return false;
for (; *a && *b; ++a, ++b) {
wchar_t x = *a, y = *b;
if (x >= L'A' && x <= L'Z') x = wchar_t(x - L'A' + L'a');
if (y >= L'A' && y <= L'Z') y = wchar_t(y - L'A' + L'a');
if (x != y) return false;
}
return *a == *b;
}

inline bool ShellPanelEq(const wchar_t* a, const wchar_t* b) {
for (; *a && *a == *b; ++a, ++b) {}
return *a == *b;
}

// cls: the window class (case-sensitive, as Windows reports it). exe: the owning process's image
// file name without its folder (compared case-insensitively). topLevel: the window is its own root.
inline ShellPanelKind ClassifyShellPanel(const wchar_t* cls, const wchar_t* exe, bool topLevel) {
if (!cls || !exe || !topLevel) return ShellPanelKind::None;
if (ShellPanelEq(cls, L"IME") && ShellPanelEqI(exe, L"TextInputHost.exe"))
return ShellPanelKind::InputPanel;
if (ShellPanelEq(cls, L"Shell_InputSwitchTopLevelWindow") && ShellPanelEqI(exe, L"explorer.exe"))
return ShellPanelKind::InputSwitcher;
return ShellPanelKind::None;
}

// Is a classified window showing right now? The input panel's IME window is never shown or hidden,
// so only its cloak counts; the input switcher must be both visible and uncloaked.
inline bool ShellPanelShowing(ShellPanelKind k, bool visible, bool cloaked) {
switch (k) {
case ShellPanelKind::InputPanel: return !cloaked;
case ShellPanelKind::InputSwitcher: return visible && !cloaked;
default: return false;
}
}

} // namespace wind
46 changes: 46 additions & 0 deletions tests/test_shell_panel.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
// Copyright (c) 2026 Max Aubert. All rights reserved.
// Proprietary source-available software; see LICENSE. SPDX-License-Identifier: LicenseRef-Wind-Proprietary
#include "doctest.h"
#include "shell_panel.h"

using wind::ClassifyShellPanel;
using wind::ShellPanelKind;
using wind::ShellPanelShowing;

TEST_CASE("shell panel: TextInputHost's IME window is an input panel") {
CHECK(ClassifyShellPanel(L"IME", L"TextInputHost.exe", true) == ShellPanelKind::InputPanel);
CHECK(ClassifyShellPanel(L"IME", L"textinputhost.EXE", true) == ShellPanelKind::InputPanel);
}

TEST_CASE("shell panel: explorer's keyboard layout menu is the input switcher (#569)") {
CHECK(ClassifyShellPanel(L"Shell_InputSwitchTopLevelWindow", L"explorer.exe", true) ==
ShellPanelKind::InputSwitcher);
CHECK(ClassifyShellPanel(L"Shell_InputSwitchTopLevelWindow", L"Explorer.EXE", true) ==
ShellPanelKind::InputSwitcher);
}

TEST_CASE("shell panel: look-alikes are not panels") {
// Every GUI thread has an IME window, explorer's included.
CHECK(ClassifyShellPanel(L"IME", L"explorer.exe", true) == ShellPanelKind::None);
CHECK(ClassifyShellPanel(L"Shell_InputSwitchTopLevelWindow", L"TextInputHost.exe", true) ==
ShellPanelKind::None);
// The dismiss overlay shows with the menu but covers the whole screen; it is not the menu.
CHECK(ClassifyShellPanel(L"Shell_InputSwitchDismissOverlay", L"explorer.exe", true) ==
ShellPanelKind::None);
CHECK(ClassifyShellPanel(L"XamlExplorerHostIslandWindow", L"explorer.exe", true) ==
ShellPanelKind::None);
CHECK(ClassifyShellPanel(L"ime", L"TextInputHost.exe", true) == ShellPanelKind::None);
CHECK(ClassifyShellPanel(L"Shell_InputSwitchTopLevelWindow", L"explorer.exe", false) ==
ShellPanelKind::None);
CHECK(ClassifyShellPanel(nullptr, L"explorer.exe", true) == ShellPanelKind::None);
CHECK(ClassifyShellPanel(L"IME", nullptr, true) == ShellPanelKind::None);
}

TEST_CASE("shell panel: input panels count by cloak alone, the switcher needs visible too") {
CHECK(ShellPanelShowing(ShellPanelKind::InputPanel, false, false));
CHECK_FALSE(ShellPanelShowing(ShellPanelKind::InputPanel, true, true));
CHECK(ShellPanelShowing(ShellPanelKind::InputSwitcher, true, false));
CHECK_FALSE(ShellPanelShowing(ShellPanelKind::InputSwitcher, false, false)); // closed (hidden)
CHECK_FALSE(ShellPanelShowing(ShellPanelKind::InputSwitcher, true, true));
CHECK_FALSE(ShellPanelShowing(ShellPanelKind::None, true, false));
}
Loading