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.

Passing some but not all of the coordinates throws a ValueError.

The corners may be given in any order.

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.

If the cursor is outside the region when ClipCursor is called, it is moved inside immediately.

ClipCursor installs the mouse hook if it is not already installed; the hook remains installed after the confinement is released.

The confinement 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.

Linux

Cursor confinement requires the keysharp-input mouse hook and a keysharp-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 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

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
}