Fix cursor not captured in headless sessions

[ilCosmico]

Fix for cursor capture failure in headless environments or after session lock/unlock. This adds a minimal synthetic mouse move using mouse_event to force Windows to redraw the cursor, preventing GetCursorInfo from returning null or CURSOR_SUPPRESSED. Based on a solution tested in FlaUI usage with automated UI testing on Windows Server and Windows 11.

[t4m45]

Just a comment from another user..

You're moving the mouse without checking if it's actually needed.
At the very least, you should move the workaround inside this if-statement and re-check to see if it worked:

if (cursorInfo.flags != CursorState.CURSOR_SHOWING)
{
    return null;
}

That said, I don't think this workaround belongs inside the capture method itself. There might already be tests relying on it to return null when the cursor is hidden.

Also, keep in mind: this breaks the system idle time, and there won’t be a clear indication of what caused it.

You should probably make your own extension method for this behavior. Something like:

[StructLayout(LayoutKind.Sequential)]
public struct CURSORINFO
{
    public Int32 cbSize;
    public CursorState flags;
    public IntPtr hCursor;
    public POINT ptScreenPos;
}

[DllImport("user32.dll")]
public static extern bool GetCursorInfo(out CURSORINFO pci);

[DllImport("user32.dll")]
private static extern void mouse_event(int dwFlags, int dx, int dy, int dwData, int dwExtraInfo);

private const int MOUSEEVENTF_MOVE = 0x0001;

public static void PokeAndCaptureCursor()
{
    var cursorInfo = new CURSORINFO();
    cursorInfo.cbSize = Marshal.SizeOf(cursorInfo);
    if (!User32.GetCursorInfo(out cursorInfo) || cursorInfo.flags != CursorState.CURSOR_SHOWING)
    {
        // Workaround for headless environments or inactive sessions:
        // Windows may suppress drawing the cursor (CURSOR_SUPPRESSED) unless there's recent mouse activity.
        // This emulates a minimal movement to force Windows to update the cursor state.
        mouse_event(MOUSEEVENTF_MOVE, 1, 1, 0, 0);
        mouse_event(MOUSEEVENTF_MOVE, -1, -1, 0, 0);

        // maybe do another check before continue
    }

    Point position = new();
    var bitmap = FlaUI.Core.Capturing.CaptureUtilities.CaptureCursor(ref position);
    // ...
}

[ilCosmico]

@t4m45 Thanks for the helpful suggestion. I tried the approach and it works great!

I understand your point about not modifying CaptureCursor() directly, and I agree that keeping it clean is important.
That said, I wonder if a method like TryForceCaptureCursor() (or PokeAndCaptureCursor()) could still be integrated into FlaUI itself, as an optional utility, since others might run into the same issue in headless environments.

If you think it's reasonable, I’d be happy to revise the PR accordingly to include it as a separate helper or extension method.

[ilCosmico]

Hi @Roemer, just following up on this after a few months.

I’d be interested to hear your point of view on this workaround. Do you think a method like TryForceCaptureCursor() could be a useful addition to FlaUI for handling edge cases (like headless or locked sessions), as an optional utility?

Happy to adjust the PR if needed. Let me know what you think! 😊