app.mouse - Mouse Simulation API

Simulates mouse operations (click, move, drag, scroll).

Permission: Requires mouse declared in the manifest (L3 dangerous) System requirement: Requires Accessibility Permission, except for position()

Methods

app.mouse.click(x, y, options?)

Clicks the mouse at the specified coordinates.

Parameters:

• x (number) - X coordinate (screen pixels)
• y (number) - Y coordinate (screen pixels)
• options (table, optional):
  • button (string, optional) - Button: "left" (default), "right", "middle"
  • clicks (number, optional) - Number of clicks (default 1, 2 for double-click)
  • modifiers (array, optional) - Modifier key array (e.g. {"cmd", "shift"})

Returns: boolean, error

-- Left click
app.mouse.click(100, 200)

-- Right click
app.mouse.click(100, 200, {button = "right"})

-- Double click
app.mouse.click(100, 200, {clicks = 2})

-- Cmd+click
app.mouse.click(100, 200, {modifiers = {"cmd"}})

app.mouse.move(x, y)

Moves the mouse to the specified coordinates.

Parameters:

• x (number) - X coordinate
• y (number) - Y coordinate

Returns: boolean, error

app.mouse.move(500, 300)

app.mouse.drag(fromX, fromY, toX, toY, options?)

Drags from one coordinate to another.

Parameters:

• fromX (number) - Start X coordinate
• fromY (number) - Start Y coordinate
• toX (number) - Target X coordinate
• toY (number) - Target Y coordinate
• options (table, optional):
  • button (string, optional) - Button: "left" (default) or "right"
  • duration (number, optional) - Drag duration in seconds (default 0.5)

Returns: boolean, error

-- Simple drag
app.mouse.drag(100, 200, 500, 400)

-- Slow drag
app.mouse.drag(100, 200, 500, 400, {duration = 2.0})

-- Right-button drag
app.mouse.drag(100, 200, 500, 400, {button = "right"})

app.mouse.position()

Gets the current mouse position.

This method does not require Accessibility Permission.

Returns: table - {x, y}

local pos = app.mouse.position()
app.log.info(string.format("Mouse position: %d, %d", pos.x, pos.y))

app.mouse.scroll(dx, dy)

Simulates scroll wheel scrolling.

Parameters:

• dx (number) - Horizontal scroll amount (positive = right, negative = left)
• dy (number) - Vertical scroll amount (positive = down, negative = up)

Returns: boolean, error

-- Scroll down
app.mouse.scroll(0, 5)

-- Scroll up
app.mouse.scroll(0, -5)

-- Horizontal scroll
app.mouse.scroll(3, 0)

Examples

Automate UI operations

function MyPlugin:handleAutomate(context)
    -- Get current mouse position
    local startPos = app.mouse.position()

    -- Move to target position and click
    app.mouse.move(200, 100)
    app.thread.sleep(0.2)
    app.mouse.click(200, 100)
    app.thread.sleep(0.5)

    -- Drag a file
    app.mouse.drag(200, 100, 500, 300, {duration = 1.0})

    -- Restore mouse position
    app.mouse.move(startPos.x, startPos.y)
end

Select a region

function MyPlugin:handleSelectRegion(context)
    -- Get the user's starting click position
    local pos = app.mouse.position()

    -- Drag to select toward the bottom-right
    app.mouse.drag(pos.x, pos.y, pos.x + 300, pos.y + 200, {
        duration = 0.3
    })
end

Notes

1. Accessibility Permission: All methods except position() require Accessibility Permission
2. Permission level: L3 dangerous; requires mouse permission declared in the manifest
3. Coordinate system: Uses screen pixel coordinates with the origin at the top-left corner of the primary display
4. Drag interpolation: drag() uses linear interpolation to generate intermediate move events, simulating a real drag
5. Modifier keys: Supports cmd/command, shift, alt/option, ctrl/control, fn