Find My Mouse

Find My Mouse is a utility that helps users locate their mouse pointer by creating a spotlight effect when activated. It is based on Raymond Chen's SuperSonar utility.

Implementation

Find My Mouse displays a spotlight effect centered on the cursor location when activated via a keyboard shortcut (typically a double-press of the Ctrl key).

Key Files

src/modules/MouseUtils/FindMyMouse/FindMyMouse.cpp - Contains the main implementation
Key function: s_WndProc - Handles window messages for the utility

Enabling Process

When the utility is enabled:

A background thread is created to run the Find My Mouse logic asynchronously:

cpp

// Enable the PowerToy
virtual void enable()
{
    m_enabled = true;  // Mark the module as enabled
    Trace::EnableFindMyMouse(true);  // Enable telemetry
    std::thread([=]() { FindMyMouseMain(m_hModule, m_findMyMouseSettings); }).detach();  // Run main logic in background
}

The CompositionSpotlight instance is initialized with user settings:

cpp

CompositionSpotlight sonar;
sonar.ApplySettings(settings, false);  // Apply settings
if (!sonar.Initialize(hinst))
{
    Logger::error("Couldn't initialize a sonar instance.");
    return 0;
}

m_sonar = &sonar;

The utility listens for raw input events using WM_INPUT, which provides more precise and responsive input detection than standard mouse events.

Activation Process

The activation process works as follows:

Keyboard Hook Detects Shortcut
- A global low-level keyboard hook is set up during initialization
- The hook monitors for the specific activation pattern (double Ctrl press)
- Once matched, it sends a WM_PRIV_SHORTCUT message to the sonar window:
  cpp
```
virtual void OnHotkeyEx() override
{
    Logger::trace("OnHotkeyEx()");
    HWND hwnd = GetSonarHwnd();
    if (hwnd != nullptr)
    {
        PostMessageW(hwnd, WM_PRIV_SHORTCUT, NULL, NULL);
    }
}
```

Message Handler Triggers Action

The custom message is routed to BaseWndProc()

The handler toggles the sonar animation:

cpp

if (message == WM_PRIV_SHORTCUT)
{
    if (m_sonarStart == NoSonar)
        StartSonar();  // Trigger sonar animation
    else
        StopSonar();   // Cancel if already running
}

Sonar Animation
- StartSonar() uses CompositionSpotlight to display a highlight (ripple/pulse) centered on the mouse pointer
- The animation is temporary and fades automatically or can be cancelled by user input

Event Handling

The Find My Mouse utility handles several types of events:

Mouse Events: Trigger sonar animations (e.g., after a shake or shortcut)
Keyboard Events: May cancel or toggle the effect
Custom Shortcut Messages: Handled to allow toggling Find My Mouse using a user-defined hotkey

When the main window receives a WM_DESTROY message (on shutdown or disable), the sonar instance is properly cleaned up, and the message loop ends gracefully.

Debugging

To debug Find My Mouse:

Attach to the PowerToys Runner process directly
Set breakpoints in the FindMyMouse.cpp file
When debugging the spotlight effect, visual artifacts may occur due to the debugger's overhead