Skip to content

Add macOS Cursor & Shake to Find (4K HD) - #7583

Open
brcarvp wants to merge 7 commits into
ramensoftware:mainfrom
brcarvp:main
Open

brcarvp wants to merge 7 commits into
ramensoftware:mainfrom
brcarvp:main

Conversation

@brcarvp

@brcarvp brcarvp commented Nov 17, 2026 •

Copy link
Copy Markdown

Add macos-cursor-shake-to-find mod

Changelog

If this pull request updates an existing mod, describe the changes inside the changelog markers:

  • Changelog item 1...
  • Changelog item 2...

Mod authorship

If this pull request introduces a new mod, please complete the section below.

This mod was created by:

    • The submitter, without AI assistance
    • The submitter, with AI assistance
    • Claude
    • ChatGPT
    • Gemini
    • Another AI (please specify):
    • Other (please specify):

Please select the options that best apply. Your selection does not affect the acceptance criteria, but it helps reviewers understand the context of the code and provide relevant feedback.

Add macos-cursor-shake-to-find mod
@windhawk-reviewer windhawk-reviewer Bot added the waiting-for-author The author's turn: request an AI review, or respond to one that was posted. label Nov 17, 2026
@windhawk-reviewer

Copy link
Copy Markdown

Thanks for the pull request! This repository uses a two-stage review: an AI review that you run yourself, followed by a human review.

To get started, comment /ai-review. Once you're happy with the result, comment /ready-for-reviewer to hand it over to a human reviewer.

See the pull request review process for the full details.

Add macos-cursor-shake-to-find.wh.cpp
Update macos-cursor-shake-to-find.wh.cpp 

now is using a version without having to use external files. now it has much more functions, i hope you guys like it
Update macos-cursor-shake-to-find.wh.cpp
@brcarvp

brcarvp commented Nov 17, 2026

Copy link
Copy Markdown
Author

/ready-for-reviewer

@windhawk-reviewer

Copy link
Copy Markdown

@brcarvp /ready-for-reviewer can't be applied here: this pull request hasn't been through an AI review yet. Comment /ai-review first.

See the pull request review process for details.

@brcarvp

brcarvp commented Nov 17, 2026

Copy link
Copy Markdown
Author

/ai-review

@windhawk-reviewer windhawk-reviewer Bot added waiting-for-ai-review An AI review was requested and is being prepared. and removed waiting-for-author The author's turn: request an AI review, or respond to one that was posted. labels Nov 17, 2026
@windhawk-reviewer

Copy link
Copy Markdown

Submission review

Note: This review was done by Claude. Due to the amount of submissions, doing a fully manual review for each pull request is no longer feasible. Thank you for understanding.

Remember: The AI reviewer can be wrong - it may misread code, flag correct code as broken, or suggest changes that make things worse. Treat its findings as suggestions to verify, not instructions to follow blindly. You're responsible for the code you submit, so if a finding doesn't hold up, say so instead of changing working code to satisfy it.

Please address the following issues. The items in the collapsed sections are optional, so it's your call whether to address them.


The mod mostly works as described, but the items below need changes before it can be merged.

1. Shaking the mouse makes the pointer disappear when the macOS theme isn't applied. The overlay bitmap g_pHighResArrowBmp is created only inside ApplyBuiltInMacOSCursors (line 882), and that function returns early when applyMacCursors is off or an excluded app is focused. The shake path doesn't check for this. HideSystemCursorsForShake() (line 1090) replaces all 14 system cursors with a blank one, then DrawScaledOverlay4K returns without drawing because the bitmap is null (line 952). So in each of these cases the pointer is invisible for the whole magnification time:

  • applyMacCursors is off and enableShakeToFind is on (shake-only use);
  • Word or another excluded app is in the foreground when Explorer starts or the mod is enabled (Wh_ModInit calls RestoreNativeWindowsCursors instead, line 1278). This contradicts the README line "Shake to Find still works perfectly inside Word".

Fix: create the 256 px overlay bitmap independently of the cursor theme, e.g. once at the start of the worker thread (and again after a settings change, on that thread), not in ApplyBuiltInMacOSCursors.

2. This should be a tool mod, not code running inside explorer.exe. The Explorer side of the mod hooks nothing. It only calls system-wide APIs: SetSystemCursor, SystemParametersInfo, GetCursorPos, GetForegroundWindow, and a topmost layered window. That is the case Mods as tools covers. Running it inside Explorer causes concrete problems:

  • When several explorer.exe processes run (for example with "Launch folder windows in a separate process"), each one starts its own ShakeMonitorThread. They all see the same GetCursorPos shake, so you get two overlays, both blanking and re-applying the system cursors, and both writing the same %TEMP% files.
  • Any crash in this code (see the settings-change races under Optional improvements) takes the shell down with it.
  • Wh_ModInit renders 36 PNG frames, writes two files, and renders and installs 12 more cursors (lines 1262–1279). When Explorer starts, this runs on its main thread before Explorer gets to do anything, so it delays shell startup.

Fix: move the theme and Shake to Find code to a tool mod: @include windhawk.exe, WhTool_ModInit / WhTool_ModSettingsChanged / WhTool_ModUninit, and the launcher snippet from the wiki copied verbatim. The existing shake-to-find-cursor and mouse-cursor-themes mods do exactly this. The SetCursor hook for Chrome/Edge/Brave can't run in a tool mod (the launcher would start from every browser process), so either drop it or ship it as a separate mod (see item 3, since no-hidden-cursor already does this).

3. Large overlap with existing mods. Every feature here already exists in the catalog:

  • mouse-cursor-themes draws its own cursor themes, including animated busy cursors, and installs them with SetSystemCursor from a tool mod. The difference is that this PR draws macOS shapes. That fits as a new theme or shape set there.
  • shake-to-find-cursor and mac-magnifying-cursor both implement macOS "Shake to Find" by enlarging the cursor. This PR differs only in drawing a macOS arrow in the overlay and in the per-app exclusion list.
  • no-hidden-cursor blocks SetCursor(NULL) the same way the browser hook here does. This PR adds a fullscreen exception.

The PR doesn't say why this should be a separate mod (the body is only the template). The maintainer prefers extending existing mods over adding near-duplicates. The path for that is an issue or PR to the authors of mouse-cursor-themes (a macOS theme) and shake-to-find-cursor / mac-magnifying-cursor (any shake behavior they lack). If you still want a separate mod, please explain why in the PR.

4. The worker thread has a visible window but no message loop, and it polls at 60 Hz forever. ShakeMonitorThread creates the top-level overlay window (line 1023), then loops on Sleep(16) (line 1112) without ever calling GetMessage / PeekMessage:

  • Nothing ever answers messages sent to that window. Broadcasts like WM_SETTINGCHANGE / WM_DISPLAYCHANGE and WM_QUERYENDSESSION at sign-out reach every top-level window. A sender using plain SendMessage hangs, and one using a timeout waits it out. After 5 seconds Windows reports the window as hung (IsHungAppWindow).
  • The loop wakes up about 30–60 times a second even when the mouse is idle. With excludeOfficeAndExternalApps on (the default), every iteration also calls OpenProcess + QueryFullProcessImageNameW on the foreground app (lines 1040, 269–315). That costs CPU and battery and keeps the CPU from idling.

Fix: make the thread event-driven with a real message loop:

  • motion through raw input (RIDEV_INPUTSINK);
  • foreground changes through SetWinEventHook(EVENT_SYSTEM_FOREGROUND, …, WINEVENT_OUTOFCONTEXT) installed on this thread, caching the excluded/not-excluded result;
  • a timer armed only while the overlay animates.

shake-to-find-cursor's WorkerThreadProc is a complete example: raw input, a high-resolution waitable timer and MsgWaitForMultipleObjectsEx. Stop the thread with PostThreadMessage(WM_QUIT) (or a message to its window) and join it.

5. Wh_ModUninit gives up waiting for the thread after 2 seconds. If the thread is still running after WaitForSingleObject(g_thread, 2000) (line 1292), the handle is closed anyway. GdiplusShutdown then runs while the thread may still be using GDI+, and the mod image is unloaded while the thread is executing inside it, which crashes Explorer. Wait with INFINITE. Nothing the thread does blocks on the engine thread, so this can't deadlock.

6. The generated .ani files go to %TEMP%, not to mod storage. CompileAnimatedCursors writes %TEMP%\mac_appstart.ani and %TEMP%\mac_wait.ani (lines 843–855) and never deletes them. Besides leaving stray files behind, this breaks the feature: ApplyBuiltInMacOSCursors loads both files again every time the theme is re-applied (lines 898–906: after every shake and every time focus leaves an excluded app). Once a temp cleaner or Storage Sense deletes them, the Wait and AppStarting cursors silently go back to the Windows ones. The generic names can also clash with other software. Use Wh_GetModStoragePath. Windhawk removes that folder together with the mod. Because storage is shared between sessions in a regular install, use a per-session subfolder, as mouse-cursor-themes does in EnsureDir. The README's "zero external files" claim should then also be reworded.

7. "Keep Cursor Visible While Typing" silently overrides a Windows setting, and it's on by default. UpdateMouseVanishSetting (lines 1225–1239) turns off the user's own "Hide pointer while typing" option system-wide. It is in-memory only and restored on unload, which is fine. But:

  • it's enabled by default, although it has nothing to do with macOS cursors (macOS itself hides the pointer while typing);
  • Windows already has this as a checkbox in Mouse settings;
  • when Explorer restarts, Wh_ModUninit doesn't run. The new instance then reads the already-modified FALSE as the "original" (line 1231), so the user's setting stays off for the rest of the session even after the mod is disabled.

Please default it to false (or drop it in favor of the Windows option). If you keep it, document it in the README.

8. Add a screenshot or GIF to the README. This is a purely visual mod, so users need to see the cursor set and the shake effect before installing.

Optional improvements

Minor polish — none of this affects users, so it's your call.

  • Settings changes race with the worker thread. Wh_ModSettingsChanged runs on the Windhawk engine thread while ShakeMonitorThread keeps running. This can crash Explorer:

    • ParseCustomExcludedApps clears and rebuilds g_settings.customExcludedList (line 1167) while the thread iterates it in IsProcessExcluded (line 305) every tick.
    • g_pHighResArrowBmp is deleted (line 1327) while the thread may be inside DrawScaledOverlay4K.
    • CompileAnimatedCursors rewrites the .ani files while the thread may be loading them.
    • g_sysCursorHidden / g_macCursorsCurrentlyApplied are plain bools written from both threads.

    Once the thread has a message loop (item 4), have Wh_ModSettingsChanged post a message to it, and do the reload, re-render and re-apply there. Then all SetSystemCursor / GDI+ work happens on one thread.

  • Use the typed hook helper. Use WindhawkUtils::SetFunctionHook(SetCursor, SetCursor_Hook, &SetCursor_Orig) instead of raw Wh_SetFunctionHook with void* casts (line 1258).

  • Use WindhawkUtils::StringSetting. Use it for cursorFillColor / cursorBorderColor / customExcludedApps instead of manual Wh_GetStringSetting + Wh_FreeStringSetting. Wh_GetStringSetting never returns NULL, so the fillStr ? fillStr : L"Black" and if (!rawStr) checks (lines 1203–1204, 1168) are dead code.

  • Use the DPI constant directly. Call SetThreadDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2) instead of GetProcAddress with the magic (HANDLE)-4 (lines 1013–1018).

  • BitmapToHCURSOR mask bitmap. It creates the mask with CreateBitmap(w, h, 1, 1, NULL) (line 747), whose contents are undefined. Pass a zeroed buffer. Also, when SetSystemCursor fails (lines 769, 900, 905), the cursor handle is never destroyed.

  • Comments in English. The section header comments are in Portuguese (e.g. lines 162, 258, 352). English would help other maintainers.

Functionality notes

Non-critical observations and ideas about the feature behavior itself.

  • The overlay ignores cursorSizeScale and per-monitor DPI. The normal cursor is SM_CXCURSOR × cursorSizeScale, but the overlay is SM_CXCURSOR × currentScale (lines 956–962). With a size scale of 200%, a shake first shrinks the pointer to about 1.05× the base size, then grows it to only 1.75× the user's normal size. SM_CXCURSOR is also the system-DPI value, so on mixed-DPI setups the base size doesn't match monitors with a different DPI.

  • The theme isn't re-applied when Windows reloads the pointer scheme. When the user picks another scheme or changes the pointer size or color in Settings, the mac cursors are replaced, but g_macCursorsCurrentlyApplied stays true, so they never come back. mouse-cursor-themes watches WM_SETTINGCHANGE / SPI_SETCURSORS for this.

  • Exclusion follows the foreground window, but system cursors are global. While Word has focus, every window gets native cursors. Hovering over Word while another app is focused shows the mac cursors. The default exclusion list (Photoshop, Illustrator, AutoCAD, Blender, VS Code) and the hard-coded winword.exe aren't explained anywhere. A sentence in the README on why would help.

  • Shake detection only looks at horizontal movement (dx, line 1060). Vertical or diagonal shakes don't trigger it.

  • A crash during magnification leaves the pointer invisible. If Explorer (or, after item 2, the tool process) dies while magnified, the blank cursors stay until something re-applies them. shake-to-find-cursor restores the scheme from an unhandled-exception filter.

  • The browser hook blocks every SetCursor(NULL), not just the typing case. Pages that hide the pointer on purpose (cursor: none custom cursors, video players, pointer-lock games in a window) keep the system arrow visible on top. The fullscreen check also looks at the foreground window, not at the window that called SetCursor.

  • The README overstates a few things.

    • "60 FPS": Sleep(16) at the default timer resolution usually sleeps about 31 ms, and the .ani files use jifRate 3, which is 20 fps.
    • "4K" / "Hardware Accelerated .ani Compilation": the cursors are rendered at SM_CXCURSOR size on the CPU with GDI+.
    • "13 system pointers": the mod replaces 14.

    Plain wording (and dropping "4K HD" from the name) would set the right expectations.

Code overview

For the maintainer: a map of the mod and what it touches outside its own process. Descriptive only — anything that needs a change is listed above. Line numbers refer to the mod source at commit 50f6c55. This mod is new, so everything below is new.

Code regions

  • Line 1–13: metadata. Injects into explorer.exe, chrome.exe, msedge.exe, brave.exe; links GDI+ and ole32.
  • Line 15–29: README.
  • Line 31–96: settings (theme toggle, size scale, fill/border color dropdowns, shake toggle/scale/sensitivity/delay, keep-visible-while-typing, exclusion toggle and list).
  • Line 98–159: includes, OCR_* fallbacks, ModSettings struct and globals.
  • Line 161–255: .ani builder helpers: PNG encoder lookup, RIFF/ACON writer, %TEMP% path helper.
  • Line 257–323: foreground-app exclusion. Resolves the foreground window's exe via OpenProcess + QueryFullProcessImageNameW and compares it with winword.exe and the custom list.
  • Line 325–349: SetCursor hook (browsers only). Swallows SetCursor(NULL) and returns the current cursor unless the foreground window covers its monitor.
  • Line 351–729: GDI+ drawing of the macOS-style shapes (arrow, up-arrow, app-starting, beachball, hand, I-beam, cross, move, resize, help, no).
  • Line 731–856: cursor construction. Bitmap → HCURSOR, a SetSystemCursor wrapper, and CompileAnimatedCursors, which builds two 18-frame PNG-in-ICO .ani files and writes them to %TEMP%.
  • Line 858–910: RestoreNativeWindowsCursors (SPI_SETCURSORS) and ApplyBuiltInMacOSCursors, which renders and installs 12 static and 2 animated system cursors and creates the 256 px overlay bitmap.
  • Line 912–1008: shake helpers. Blank cursor, replacement of all system cursors with it, and the scaled arrow drawn into the layered overlay via UpdateLayeredWindow.
  • Line 1010–1120: ShakeMonitorThread. Creates the overlay window, then runs a 16 ms polling loop: exclusion-driven theme switching, horizontal-reversal shake detection, scale animation, overlay show/hide.
  • Line 1122–1223: settings loading. Color-name mapping, exclusion-list parsing, LoadSettings.
  • Line 1225–1249: SPI_SETMOUSEVANISH override and Explorer process check.
  • Line 1251–1284: Wh_ModInit. Browsers: installs the SetCursor hook. Explorer: starts GDI+, overrides mouse vanish, compiles the .ani files, applies or restores cursors, starts the thread.
  • Line 1286–1309: Wh_ModUninit. Stops the thread (2 s wait), frees the bitmap, shuts down GDI+, restores mouse vanish and the user's cursor scheme.
  • Line 1311–1336: Wh_ModSettingsChanged. Reloads settings and, in Explorer, recompiles the .ani files and re-applies or restores the cursors.

Side effects of interest

  • Line 843–855: external file write: %TEMP%\mac_appstart.ani and %TEMP%\mac_wait.ani, overwritten in Explorer at Wh_ModInit and on every settings change. Never deleted, so they remain after the mod is disabled.
  • Line 898–906: external file read: the same two files, loaded with LoadImageW(LR_LOADFROMFILE) each time the theme is applied (init, settings change, the end of every shake, focus leaving an excluded app).
  • Line 762–770, 898–906: system settings change: SetSystemCursor replaces 14 system cursors for the whole session (all apps), whenever the theme is applied.
  • Line 931–949: system settings change: SetSystemCursor sets all 14 system cursors to a blank cursor while the shake overlay is shown.
  • Line 858–865: system settings change: SPI_SETCURSORS (no ini update) reloads the user's cursor scheme when an excluded app is focused, when the theme is off, and on unload.
  • Line 1225–1239, 1304–1307: system settings change: SPI_SETMOUSEVANISH set to FALSE system-wide (no ini update) at init and on settings change when "keep visible while typing" is on. The saved value is restored when the option is turned off and on unload.
  • Line 269–315 (called from line 1040 every loop iteration, and from lines 1275 and 1331): other reach outside the process: OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION) + QueryFullProcessImageNameW on the foreground window's process, about every 16–31 ms while the exclusion option is on.


Next steps:

  • /ai-review - after pushing fixes, to get a review of the updated code. You can repeat this as many times as you need, but each review is thorough and usually there's no need for more than 2-3 iterations.
  • /ready-for-reviewer - once you're satisfied with the state of the pull request, to hand it over to a human reviewer. If some findings above are left unaddressed, add a short note explaining why.

See the review process for details.

Important: Each reply that was generated by AI must be disclosed by including the following text in the reply: "Generated by AI. Model: (ai-model-name)".

@windhawk-reviewer windhawk-reviewer Bot added waiting-for-author The author's turn: request an AI review, or respond to one that was posted. and removed waiting-for-ai-review An AI review was requested and is being prepared. labels Nov 17, 2026
Update macos-cursor-shake-to-find.wh.cpp
@brcarvp

brcarvp commented Nov 18, 2026

Copy link
Copy Markdown
Author

/ai-review

@windhawk-reviewer windhawk-reviewer Bot added waiting-for-ai-review An AI review was requested and is being prepared. and removed waiting-for-author The author's turn: request an AI review, or respond to one that was posted. labels Nov 18, 2026
@windhawk-reviewer

Copy link
Copy Markdown

Submission review

Note: This review was done by Claude. Due to the amount of submissions, doing a fully manual review for each pull request is no longer feasible. Thank you for understanding.

Remember: The AI reviewer can be wrong - it may misread code, flag correct code as broken, or suggest changes that make things worse. Treat its findings as suggestions to verify, not instructions to follow blindly. You're responsible for the code you submit, so if a finding doesn't hold up, say so instead of changing working code to satisfy it.

Please address the following issues. The items in the collapsed sections are optional, so it's your call whether to address them.


Thanks for the update. These earlier items are resolved:

  • it's now a tool mod;
  • the worker thread pumps messages;
  • WhTool_ModUninit waits for the thread with INFINITE;
  • the README has a screenshot;
  • the shake overlay now enlarges the native cursor when the macOS theme is off or an excluded app is focused;
  • the "Hide pointer while typing" override is gone.

Three items still need changes:

1. Large overlap with existing mods (not addressed yet). Every feature here already exists in the catalog:

  • mouse-cursor-themes draws its own cursor themes, including animated busy cursors, and installs them with SetSystemCursor from a tool mod. The difference is that this PR draws macOS shapes. That fits as a new theme or shape set there.
  • shake-to-find-cursor and mac-magnifying-cursor are both tool mods that implement macOS "Shake to Find" by enlarging the cursor. This PR differs in drawing a 256 px macOS arrow in the overlay and in the per-app exclusion list.

The PR still doesn't say why this should be a separate mod: the body is only the template, and there's no comment about it. The maintainer prefers extending existing mods over adding near-duplicates. The path for that is an issue or PR to the authors of mouse-cursor-themes (a macOS theme) and shake-to-find-cursor / mac-magnifying-cursor (the high-resolution arrow overlay, app exclusions). If you still want a separate mod, please explain why in the PR so the maintainer can decide.

2. The worker thread still polls about 60 times a second, forever. The message pump fixed the hung-window problem. But MsgWaitForMultipleObjects still uses a 16 ms timeout (line 1008), so the thread wakes up 30–60 times a second even when the mouse is idle. With excludeOfficeAndExternalApps on (the default), each wake-up also calls OpenProcess + QueryFullProcessImageNameW on the foreground app (line 1021 → lines 247–285). That costs CPU and battery and keeps the CPU from idling, for as long as the user is signed in.

Now that the thread has a message loop, both inputs can be event-driven:

  • Mouse motion: give the overlay class its own window procedure and register raw input on it (RIDEV_INPUTSINK). Feed the shake detector from WM_INPUT deltas.
  • Foreground changes: call SetWinEventHook(EVENT_SYSTEM_FOREGROUND, …, WINEVENT_OUTOFCONTEXT) on this thread, and cache the excluded/not-excluded result there instead of checking it on every tick.
  • Timeout: wait with INFINITE while idle, and use the short timeout (or a waitable timer) only while a shake is being tracked or the overlay animates.

shake-to-find-cursor's WorkerThreadProc does exactly this with raw input, a high-resolution waitable timer and MsgWaitForMultipleObjectsEx.

3. The generated .ani files still go to %TEMP% (not addressed yet). CompileAnimatedCursors writes %TEMP%\mac_appstart.ani and %TEMP%\mac_wait.ani (lines 737–752) and never deletes them. This leaves stray files behind, and it also breaks the feature. ApplyBuiltInMacOSCursors loads both files again every time the theme is re-applied (lines 842–852): after every shake and every time focus leaves an excluded app. Once a temp cleaner or Storage Sense deletes them, the Wait and AppStarting cursors silently go back to the Windows ones until the next settings change. The generic names can also clash with other software.

Use Wh_GetModStoragePath instead. Windhawk removes that folder together with the mod. Mod storage is shared by the tool processes of all signed-in sessions in a regular install, so use a per-session subfolder, as mouse-cursor-themes does in EnsureDir.

Optional improvements

Minor polish — none of this affects users, so it's your call.

  • Settings changes still race with the worker thread. WhTool_ModSettingsChanged runs on the Windhawk engine thread while ShakeMonitorThread keeps running:

    • ParseCustomExcludedApps clears and rebuilds g_settings.customExcludedList (line 1165) while the thread iterates it in IsProcessExcluded (line 272).
    • g_pHighResArrowBmp is deleted (lines 1288–1291) while the thread may be drawing it (line 952).
    • CompileAnimatedCursors rewrites the .ani files (line 1286) while the thread may be loading them.
    • ApplyBuiltInMacOSCursors can run on both threads at once (lines 1294 and 1028/1099). It reads and writes the plain bool flags on lines 152–153, and both threads may create g_pHighResArrowBmp.

    A crash now only takes down the tool process, but that leaves the system cursors as they were (blank if it happens during a shake), and nothing restarts the tool. Since the thread has a message loop now, have WhTool_ModSettingsChanged post a message to the overlay window (or set an event the loop waits on). Then do the reload, re-render and re-apply on the worker thread, so all SetSystemCursor / GDI+ work stays on one thread.

  • Use WindhawkUtils::StringSetting. Use it for cursorFillColor / cursorBorderColor / customExcludedApps instead of manual Wh_GetStringSetting + Wh_FreeStringSetting (lines 1194–1206, 1217–1219). Wh_GetStringSetting never returns NULL, so the fillStr ? fillStr : L"Black" and if (!rawStr) checks (lines 1201–1202, 1166) are dead code.

  • Use the DPI constant directly. Call SetThreadDpiAwarenessContext(DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2) instead of GetProcAddress with the magic (HANDLE)-4 (lines 982–988).

  • BitmapToHCURSOR mask bitmap. It creates the mask with CreateBitmap(w, h, 1, 1, NULL) (line 773), whose contents are undefined. Pass a zeroed buffer. When SetSystemCursor fails (lines 807–851), the cursor handle is never destroyed.

  • Unused includes. <shlobj.h> and <cmath> aren't used.

  • Launcher formatting. The launcher boilerplate (lines 1300–1458) is the wiki snippet with its lines re-wrapped. The code is identical, but keeping it byte-for-byte makes future comparisons with the wiki trivial.

  • Comments in English. The section header comments are in Portuguese (e.g. lines 157, 238, 288, 859, 1121, 1223). English would help other maintainers.

Functionality notes

Non-critical observations and ideas about the feature behavior itself.

  • The enlarged native cursor loses its soft edges. In native mode the overlay converts the captured cursor with Gdiplus::Bitmap::FromHICON (line 946). That is known to drop the partial alpha of 32-bit cursors, so the Windows cursor's shadow and anti-aliased edges can come out as dark fringes once scaled up 3.5×. Reading the color bitmap from GetIconInfo with GetDIBits into a PixelFormat32bppARGB bitmap keeps the alpha.
  • The fallback cursor can show up blank. When GetCursorInfo returns no cursor, the fallback LoadImageW(NULL, IDC_ARROW, …, LR_SHARED) (line 1077) returns the system arrow handle itself. Its image is then swapped for the blank cursor by HideSystemCursorsForShake on the next line, so the overlay draws nothing. It's also a shared handle, which DestroyIcon (lines 1091, 1109) must not be called on. Load it without LR_SHARED, or CopyIcon it before hiding the cursors.
  • The overlay always draws the arrow while the macOS theme is active. It doesn't follow the current cursor shape (I-beam, hand, …), although the setting now says "Temporarily enlarges the current cursor".
  • The overlay ignores cursorSizeScale and per-monitor DPI. The normal cursor is SM_CXCURSOR × cursorSizeScale, but the overlay is SM_CXCURSOR × currentScale (lines 898–903). With a size scale of 200%, a shake first shrinks the pointer to about 1.05× the base size, then grows it to only 1.75× the user's normal size. SM_CXCURSOR is also the system-DPI value, so on mixed-DPI setups the base size doesn't match monitors with a different DPI.
  • The theme isn't re-applied when Windows reloads the pointer scheme. When the user picks another scheme or changes the pointer size or color in Settings, the mac cursors are replaced, but g_macCursorsCurrentlyApplied stays true, so they never come back. The overlay window receives the broadcast now, so a window procedure that handles WM_SETTINGCHANGE with SPI_SETCURSORS can re-apply them. See mouse-cursor-themes' MsgWndProc.
  • Exclusion follows the foreground window, but system cursors are global. While Word has focus, every window gets native cursors. Hovering over Word while another app is focused shows the mac cursors. The default exclusion list (Photoshop, Illustrator, AutoCAD, Blender, VS Code) and the hard-coded winword.exe aren't explained anywhere. A sentence in the README on why would help.
  • Shake detection only looks at horizontal movement (dx, line 1033). Vertical or diagonal shakes don't trigger it.
  • A crash during magnification leaves the pointer invisible. If the tool process dies while magnified, the blank cursors stay until the user signs out or reloads the pointer scheme. shake-to-find-cursor restores the scheme from an unhandled-exception filter.
  • The name and README still overstate things. "4K HD" and "4K macOS cursor suite" in the name, description and README, plus "Hardware Accelerated .ani Compilation … securely": the cursors are rendered on the CPU with GDI+ at SM_CXCURSOR size, and only the overlay arrow uses a 256 px source. Plainer wording would set the right expectations.

Code overview

For the maintainer: a map of the mod and what it touches outside its own process. Descriptive only — anything that needs a change is listed above. Line numbers refer to the mod source at commit 6101b21. This mod is new, so everything below is new.

Code regions

  • Line 1–10: metadata. Tool mod (windhawk.exe); links shell32, GDI+ and ole32.
  • Line 12–27: README with an i.imgur.com screenshot.
  • Line 29–91: settings (theme toggle, size scale, fill/border color dropdowns, shake toggle/scale/sensitivity/delay, exclusion toggle and list).
  • Line 93–154: includes, OCR_* fallbacks, ModSettings struct and globals (stop event, thread, overlay window, overlay bitmap, state flags, GDI+ token).
  • Line 156–235: .ani builder helpers: %TEMP% path helper, PNG encoder lookup, RIFF/ACON writer.
  • Line 237–285: foreground-app exclusion. Resolves the foreground window's exe via OpenProcess + QueryFullProcessImageNameW and compares it with winword.exe and the custom list.
  • Line 287–661: GDI+ drawing of the macOS-style shapes (arrow, up-arrow, app-starting, beachball, hand, I-beam, cross, move, resize, help, no).
  • Line 663–753: CompileAnimatedCursors. Builds two 18-frame PNG-in-ICO .ani files and writes them to %TEMP%.
  • Line 755–856: RestoreNativeWindowsCursors (SPI_SETCURSORS), BitmapToHCURSOR, and ApplyBuiltInMacOSCursors, which renders and installs 12 static and 2 animated system cursors and creates the 256 px overlay bitmap.
  • Line 858–979: shake helpers. Blank cursor, replacement of all system cursors with it, and DrawScaledOverlay4K, which scales either the 256 px mac arrow or the captured native cursor into the layered overlay via UpdateLayeredWindow.
  • Line 981–1118: ShakeMonitorThread. Creates the overlay window, then runs a MsgWaitForMultipleObjects loop (16 ms timeout plus a PeekMessage pump) that switches the theme for excluded apps, detects horizontal reversals, captures the current cursor when magnification starts, animates the scale and shows or hides the overlay.
  • Line 1120–1220: settings loading. Color-name mapping, exclusion-list parsing, LoadSettings.
  • Line 1222–1251: WhTool_ModInit. Starts GDI+, compiles the .ani files, applies or restores the cursors, creates the stop event, starts the thread.
  • Line 1253–1275: WhTool_ModUninit. Signals the stop event, joins the thread (INFINITE), frees the bitmap, shuts down GDI+, restores the user's cursor scheme.
  • Line 1277–1298: WhTool_ModSettingsChanged. On the engine thread: reloads settings, recompiles the .ani files, deletes the overlay bitmap, re-applies or restores the cursors.
  • Line 1300–1458: tool mod launcher boilerplate (the wiki snippet, re-wrapped).

Side effects of interest

  • Line 737–752: external file write: %TEMP%\mac_appstart.ani and %TEMP%\mac_wait.ani, overwritten at WhTool_ModInit and on every settings change. Never deleted, so they remain after the mod is disabled.
  • Line 842–852: external file read: the same two files, loaded with LoadImageW(LR_LOADFROMFILE) each time the theme is applied (init, settings change, the end of every shake, focus leaving an excluded app).
  • Line 806–852: system settings change: SetSystemCursor replaces 14 system cursors for the whole session (all apps), whenever the theme is applied.
  • Line 877–895: system settings change: SetSystemCursor sets all 14 system cursors to a blank cursor while the shake overlay is shown.
  • Line 755–759: system settings change: SPI_SETCURSORS (no ini update) reloads the user's cursor scheme when an excluded app is focused, when the theme is off, at the end of a shake in native mode, and on unload.
  • Line 247–285 (called from line 1021 on every loop iteration, and from lines 1240 and 1293): other reach outside the process: OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION) + QueryFullProcessImageNameW on the foreground window's process, about every 16–31 ms while the exclusion option is on.
  • Line 1387–1441: other reach outside the process: the standard launcher starts windhawk.exe -tool-mod "macos-cursor-shake-to-find" with CreateProcessInternalW when the mod loads in the Windhawk tray process.


Next steps:

  • /ai-review - after pushing fixes, to get a review of the updated code. You can repeat this as many times as you need, but each review is thorough and usually there's no need for more than 2-3 iterations.
  • /ready-for-reviewer - once you're satisfied with the state of the pull request, to hand it over to a human reviewer. If some findings above are left unaddressed, add a short note explaining why.

See the review process for details.

Important: Each reply that was generated by AI must be disclosed by including the following text in the reply: "Generated by AI. Model: (ai-model-name)".

@windhawk-reviewer windhawk-reviewer Bot added waiting-for-author The author's turn: request an AI review, or respond to one that was posted. and removed waiting-for-ai-review An AI review was requested and is being prepared. labels Nov 18, 2026
@brcarvp

brcarvp commented Nov 18, 2026

Copy link
Copy Markdown
Author

The main reason this is submitted as a standalone suite rather than extending mouse-cursor-themes or shake-to-find-cursor is that it bridges a highly specific gap: it provides a procedural vector-based macOS shape generator that dynamically scales to 4K without bitmap pixelation, and combines it natively with an intelligent 'Shake to Find' feature that intercepts and magnifies the actual underlying Windows cursors in excluded apps (like Word).
Attempting to force procedural vector generation, runtime .ani compilation, and app-specific native cursor magnification exclusions into the existing theme engine would completely rewrite the scope of those separate tools. This suite was designed from the ground up as a native macOS-specific emulation tool rather than a generic theme loader.

Update macos-cursor-shake-to-find.wh.cpp
Update macos-cursor-shake-to-find.wh.cpp
@brcarvp

brcarvp commented Nov 18, 2026

Copy link
Copy Markdown
Author

/ai-review

@windhawk-reviewer windhawk-reviewer Bot added waiting-for-ai-review An AI review was requested and is being prepared. and removed waiting-for-author The author's turn: request an AI review, or respond to one that was posted. labels Nov 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

waiting-for-ai-review An AI review was requested and is being prepared.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant