Mouse Module
#mouse.pressed boolean mouse.pressed(number vk)

Returns true if the given mouse button was pressed in this logic cycle. It does not continually return true when a button is held down, only once when it is initially pressed.

#mouse.released boolean mouse.released(number vk)

Returns true if the given mouse button was released in this logic cycle. It does not continually return true when a button is not held down, only once when it is initially pressed.

#mouse.isDown boolean mouse.isDown(number vk)

Returns true if the given mouse button is held down. This will continually return true as long as the button is down.

#mouse.press boolean mouse.press(number vk) boolean mouse.press(number vk, boolean async)

Attempts to send a synthetic press (click) for the given key. If 'async' is true (default), it is queued for automatic release and the script continues. Otherwise, execution is blocked (the script freezes for a few milliseconds) then sends a release signal before continuing script execution.

Example: mouse.press(key.VK_LMOUSE); -- Left click at wherever the mouse cursor currently is
#mouse.hold boolean mouse.hold(number vk)

Attempts to send a synthetic hold for the given button. As there is no automatically-paired release, the async flag is not accepted in this function. The hold will remain until mouse.release() is called on this same button.

#mouse.release boolean mouse.release(number vk)

Attempts to send a synthetic release for the given button. You should typically use mouse.hold() on the button first to give it something to release.

#mouse.move mouse.move(number dx, number dy)

Attempts to move (not set to a position) the physical mouse cursor. 'dx' and 'dy' are the amount to move in pixels in the x and y axis, respectively.

#mouse.wheelMove mouse.wheelMove(number delta)

Attempts to move the physical mouse wheel. 'delta' specified the amount to move; 120 = 1 wheel click. If 'delta' is positive, moves the wheel up (away from user). If 'delta' is negative, moves the wheel down (towards user).

#mouse.setPosition mouse.setPosition(number x, number y)

Attempts to set the physical mouse cursor to the given coordinates. 'x' and 'y' are specified in pixels.

#mouse.getPosition number x, number y mouse.getPosition()

Returns the current position of the physical mouse cursor, in pixels.

#mouse.getConsolePosition number x, number y mouse.getConsolePosition()

Returns the position of the physical mouse cursor in console characters, not pixels.

NOTE: This returns the position inside the console window, not globally. Therefor, if the mouse cursor is to the left or above the console window, you can receive negative numbers. Likewise, if the cursor is to the right or below the console window, you can receive numbers larger than the console width/height in characters.

By default in Windows, a console window is typically 80 characters wide and 25 characters high, with a buffer (the total scrollable area) that is 300 characters high.

#mouse.virtualPress mouse.virtualPress(number hwnd, number vk) mouse.virtualPress(number hwnd, number vk, boolean async)

Attempts to send a synthetic press for the given button, and sends that input directly to the given window. If 'async' is true (default), it is queued for automatic release. Otherwise, execution is blocked while waiting for release.

The position that the mouse is "clicked" is wherever the virtual mouse is positioned to (use mouse.virtualMove() or mouse.setVirtualPosition() first).

As virtual functions send the input directly to the specified window's input queue, this can be used to control windows that are in the background without interrupting the user.

Example: -- Click the mouse at (200,300) mouse.setVirtualPosition(200, 300); mouse.virtualPress(key.VK_LMOUSE);
#mouse.virtualHold mouse.virtualHold(number hwnd, number vk)

Attempts to send a synthetic hold for the given button, and sends that input directly to the given window.

The position that the button is held is wherever the virtual mouse is currently positioned.

#mouse.virtualRelease mouse.virtualRelease(number hwnd, number vk)

Attempts to send a synthetic release for the given button, and sends that input directly to the given window.

The position that the button is released is wherever the virtual mouse is currently positioned.

#mouse.virtualMove mouse.virtualMove(number hwnd, number dx, number dy)

Moves the virtual mouse cursor by dx, dy. This does not affect the physical mouse cursor. See mouse.move() for more details.

#mouse.virtualWheelMove mouse.virtualWheelMove(number hwnd, number delta)

Moves the virtual mouse wheel by 'delta'. See mouse.wheelMove() for more details.

#mouse.setVirtualPosition mouse.setVirtualPosition(number hwnd, number x, number y)

Sets the virtual mouse cursor to (x, y). This does not affect the physical mouse cursor. See mouse.setPosition() for more details.

#mouse.getVirtualPosition number x, number y mouse.getVirtualPosition()

Returns the position of the virtual mouse cursor. See mouse.getPosition() for more details.

#mouse.setHookCallback boolean mouse.setHookCallback(nil) boolean mouse.setHookCallback(function callback)

Install or uninstall a mouse hook callback. If 'callback' is a Lua function, this will be the callback function used when input is trapped. The callback should accept at minimum one parameter: the virtual key code of the event. Button presses will return the virtual key code (ie. key.VK_LMOUSE) as well as the string "up" or "down" to distinguish the action performed on that button.

Moving the mouse will return the virtual key code (key.VK_MOUSEMOVE) and the position (x,y coordinates) of the mouse cursor. A mouse wheel movement event pushes the virtual key code (key.VK_MOUSEWHEEL) as well as the delta (change) in increments of 120; generally moving the wheel up will return '120' and down will return '-120'.

Your callback should return a boolean: true if you want to drop/ignore the key, or false if you want to let it fall through to be processed.

If 'callback' is nil, the mouse hook will be removed.

Both your callback and main function (macro.main) should execute very quickly so do not use any rests or pauses. Slow-executing loops here can cause the system to delay input until theis function return. If your callback takes too long (5 seconds by default) to respond, Windows will consider it timed-out and remove the hook.

When script execution is finished, the hook will also be removed automatically.

Example: function mouse_hook(vk, ...) if( vk == key.VK_MOUSEWHEEL ) then local dist = ...; printf("Mouse wheel moved %d\n", dist); elseif( vk == key.VK_MOUSEMOVE ) then local x,y = ...; printf("Mouse moved to: %d,%d\n", x, y); elseif( vk == key.VK_LMOUSE ) then local state = ...; printf("Mouse left %s\n", state); elseif( vk == key.VK_MMOUSE ) then local state = ...; printf("Middle mouse %s\n", state); elseif( vk == key.VK_RMOUSE ) then local state = ...; printf("Mouse right %s\n", state); elseif( vk == key.VK_XMOUSE1 ) then local state = ...; printf("Extended mouse button 1 %s\n", state); elseif( vk == key.VK_XMOUSE2 ) then local state = ...; printf("Extended mouse button 2 %s\n", state); return true; -- Block this message from processing (ie. ignore this event) else printf("Unhandled event: 0x%x\n", vk); end return false; end function macro.init() -- Once the hook is installed, we will capture various mouse events -- as they are generated and block the X-mouse 2 from being pressed mouse.setHookCallback(mouse_hook); end

Page last updated at 2018-09-25 20:48:11


Copyright 2018