Keyboard Module

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

pressed

boolean keyboard.pressed(number vk)

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

released

boolean keyboard.released(number vk)

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

isDown

boolean keyboard.isDown(number vk)

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

getToggleState

boolean keyboard.getToggleState(number vk)

Returns the toggle state (true = on, false = off) for the given key identified by vk. For example, you can check if Caps Lock is on with the following:

print("Caps lock ?", keyboard.getToggleState(key.VK_CAPSLOCK));

setToggleState

keyboard.setToggleState(number vk, boolean status)

Sets the toggle state of a key to 'status'. true = on, false = off.

press

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

Attempts to send a synthetic press for the given key. 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

keyboard.hold(number vk)

Attempts to send a synthetic hold for the given key. 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

keyboard.release(number vk)

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

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

virtualPress

keyboard.virtualPress(number hwnd, number vk[, boolean async])

Attempts to send a synthetic press for the given key, 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.

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

keyboard.virtualHold(number hwnd, number vk)

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

virtualRelease

keyboard.virtualRelease(number hwnd, number vk)

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

virtualType

keyboard.virtualType(number hwnd, string msg)

Attempts to send a synthetic message to a window, as if the user typed it.

getKeyName

string keyboard.getKeyName(number vk)

Returns the name of a key (given by virtual key code) as a string.

setHookCallback

boolean keyboard.setHookCallback(nil|function callback)

Install or uninstall a keyboard hook callback. If 'callback' is a Lua function, this will be the callback function used when input is trapped. The callback should accept two parameters (the virtual key code of the key that was pressed, and the event type [string "up"|"down"]) and 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 keyboard 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.

NOTE: The CTRL+ALT+DELETE keyboard combo cannot be blocked by a low-level keyboard hook. That is processed at the driver-level.

Example

function hook(vk, state)
	-- If the user presses the Windows keys, ignore them completely
	-- Otherwise, let the keypress go through.

	if( state == "down" and (vk == key.VK_LWIN or vk == key.VK_RWIN) ) then
		return true;
	else
		return false;
	end
end

function macro.init()
	-- Once the hook is installed, our system should now stop responding to the Windows keys being pressed.
	keyboard.setHookCallback(hook);
end