Mouse Module

Most mouse functions will expect a virtual key code. Use the Key Module for getting the proper VK.

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.

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 not held down, only once when it is initially released.

isDown

boolean mouse.isDown(number vk)

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

press

mouse.press(number vk[, bool async])

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

This will send the input to whichever window has input focus at the time.

hold

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.

This will send the input to whichever window has input focus at the time.

release

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.

This will send the input to whichever window has input focus at the time.

move

mouse.move(number x, number y)

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.

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).

setPosition

mouse.setPosition(number x, number y)

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

NOTE: Microsoft, in their infinite wisdom, decided to use some goofy, brain-dead system for this and we lose accuracy when normalizing the screen coordinates. As a result, the actual cursor may be 1 or 2 pixels off our target.

getPosition

number x, number y mouse.getPosition()

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

getConsolePosition

number x, number y mouse.getConsolePosition()

Returns the position of the physical mouse cursor in console characters.

NOTE: This returns the position inside the window, not globally. Therefor, if the mouse is to the left or above the console window, you can receive negative numbers.

virtualPress

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()).

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.

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 positioned to (use mouse.virtualMove() or mouse.setVirtualPosition()).

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 release is wherever the virtual mouse is positioned to (use mouse.virtualMove() or mouse.setVirtualPosition()).

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.

virtualWheelMove

mouse.virtualWheelMove(number hwnd, number delta)

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

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.

getVirtualPosition

number x, number y mouse.getVirtualPosition()

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

setHookCallback

boolean mouse.setHookCallback(nil|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 position. 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 these functions 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