ClipCursor

Confines the mouse cursor to a rectangular region of the screen, or releases an active confinement.

This function is exported by the KS module.

ClipCursor(X1, Y1, X2, Y2)

Parameters

X1, Y1

Type: Integer

The coordinates of one corner of the region, in screen coordinates.

X2, Y2

Type: Integer

The coordinates of the opposite corner, in screen coordinates. This corner is exclusive: a cursor confined by ClipCursor(0, 0, 100, 100) can reach x 99 but not x 100.

Pass either all four coordinates or none. Passing some but not all of them throws a ValueError.

The corners may be given in any order; the region is normalized before it is applied.

Return Value

This function does not return a meaningful value.

Remarks

Calling ClipCursor with no parameters releases any active confinement:

ClipCursor()  ; The cursor can move freely again.

Only physical mouse movement is confined. Movement produced by the script, such as MouseMove or Click, passes through the region boundary, so a script can still place the cursor anywhere on the screen while a confinement is active.

If the cursor is outside the region when ClipCursor is called, it is moved inside immediately rather than waiting for the next movement.

The confinement is enforced through the mouse hook, which is installed automatically if it is not already running and is left installed after the confinement is released. This mirrors the behavior of BlockInput's MouseMoveOff mode.

A confinement belongs to the running script, not to a window. It stays in effect regardless of which window is active, until it is released or the script exits. Because a confined cursor is easy to mistake for a frozen system, release it as soon as it is no longer needed.

Windows

Cursor confinement is available through the low-level mouse hook and requires no additional setup.

Linux

Cursor confinement requires the keysharp-inputd mouse hook and a desktop backend which can both query and move the cursor. If either is unavailable, the function throws an OSError. See Installing on Linux and Linux Platform Support.

macOS

Cursor confinement is implemented by monitoring and suppressing out-of-bounds physical movement. It requires both Input Monitoring and Accessibility permission. If the global mouse hook cannot be activated, the function throws an OSError. See macOS Permissions.

Related

MouseGetPos, MouseMove, BlockInput, KS module

Examples

#Import "Ks" { ClipCursor }

ClipCursor(0, 0, A_ScreenWidth // 2, A_ScreenHeight // 2)
Sleep 3000
ClipCursor()

#Import "Ks" { ClipCursor }

WinGetPos &X, &Y, &W, &H, "A"
ClipCursor(X, Y, X + W, Y + H)

Esc::
{
    ClipCursor()
    ExitApp
}