Keyboard Module
#keyboard.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.

 #keyboard.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.

 #keyboard.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.

#keyboard.getToggleState boolean keyboard.getToggleState(number vk)

Returns the toggle state (true = on, false = off) for the given key identified by 'vk'.

@code() print("Is caps lock on?", keyboard.getToggleState(key.VK_CAPSLOCK)); @endcode #keyboard.setToggleState keyboard.getToggleState(number vk, boolean status)

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

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

Attempts to send a synthetic press 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.

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

In order to send a key combination such as CTRL+C, you might consider holding the modifier, sending the key press, then releasing the modifier.

@code() keyboard.hold(key.VK_LCONTROL); keyboard.press(key.VK_C); keyboard.release(key.VK_LCONTROL); @endcode #keyboard.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. The hold will remain until keyboard.release() is called on this same button.

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

 #keyboard.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.

 #keyboard.virtualPress keyboard.virtualPress(number hwnd, number vk) 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. (See keyboard.press() for more details)

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.

 #keyboard.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.

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.

 #keyboard.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.

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.

 #keyboard.virtualType keyboard.virtualType(number hwnd, string msg)

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

 #keyboard.getKeyName string keyboard.getKeyName(number vk)

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

@code() print(keyboard.getKeyName(key.VK_ENTER)); -- Prints: Enter print(keyboard.getKeyName(65)); -- Prints: A @endcode #keyboard.setHookCallback keyboard.setHookCallback(nil) keyboard.setHookCallback(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.

@code() 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 @endcode

Page last updated at 2018-09-25 20:47:52

Copyright 2026