Skip to main content

! Create and connect a hardware mouse object (mouse.connect)

This function is available in versions after 20260805

Declaration​

mouse_obj, error_message = mouse.connect([ properties ])

Parameters​

  • properties Table, optional. Sets hardware mouse properties.

Returns​

  • mouse_obj Hardware mouse object on success; nil if creation fails.
  • error_message String. The reason creation failed.

Description​

Each call creates an independent mouse object with its own button state and connection lifecycle. A successful return means that the object is ready to use; whether the target app responds still depends on iOS and the app. This function yields the current Lua execution thread while waiting for the connection.

properties may be omitted. The following are commonly used configurable properties and their default values:

{
    VendorID = 0x5858,
    ProductID = 0x0006,
    VersionNumber = 1,
    Product = "XXTouch Mouse",
    Manufacturer = "XXTouch",
    Transport = "USB",
}

You may also set SerialNumber and LocationID. Other properties are not guaranteed to take effect. Transport only affects how iOS or the target app identifies the mouse. Setting it to "BluetoothLowEnergy" does not create a Bluetooth connection, advertise or pair the device, or make it appear in another device's Bluetooth list. If any mouse operation fails to send input, the object automatically releases all buttons and disconnects. The operation is not retried as touch input.

Example​

local m, err = mouse.connect({
    Product = "XXTouch Mouse",
})
assert(m, err)

assert(m:move(100, 0))
assert(m:down("left"))
assert(m:move(100, 50))
assert(m:up("left"))
assert(m:click("right", 60))
assert(m:click(13))
assert(m:scroll(0, 10))

m:disconnect()