Keyboard Module - Revision history

Elverion: /* setHookCallback */

2015-06-20T01:16:28Z

‎setHookCallback

Elverion: /* setHookCallback */

2015-06-08T16:52:27Z

‎setHookCallback

Elverion at 16:50, 8 June 2015

2015-06-08T16:50:03Z

Elverion at 16:51, 12 April 2015

2015-04-12T16:51:52Z

Elverion at 18:32, 14 November 2014

2014-11-14T18:32:14Z

Elverion: /* press */

2014-10-15T04:06:26Z

‎press

Elverion: /* virtualRelease */

2014-09-29T23:34:36Z

‎virtualRelease

Elverion: Protected "Keyboard Module" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

2014-06-03T18:31:45Z

Protected "Keyboard Module" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

Elverion: Created page with "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 tr..."

2014-06-02T19:27:24Z

Created page with "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 tr..."

New page

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:
<source lang="lua">
print("Caps lock ?", keyboard.getToggleState(key.VK_CAPSLOCK));
</source>

== press ==
'''keyboard.press(number vk)'''

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.

@@ Line 98: / Line 98: @@
 '''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 one parameter (the virtual key code of the key that was pressed) 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.
+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.
@@ Line 109: / Line 109: @@
 ''Example''
 <source lang="lua">
-function hook(vk)
+function hook(vk, state)
 	-- If the user presses the Windows keys, ignore them completely
 	-- Otherwise, let the keypress go through.
-	if( vk == key.VK_LWIN or vk == key.VK_RWIN ) then
+	if( state == "down" and (vk == key.VK_LWIN or vk == key.VK_RWIN) ) then
 		return true;
 	else

@@ Line 102: / Line 102: @@
 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.
+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.''

← Older revision		Revision as of 16:50, 8 June 2015
Line 93:		Line 93:

	Returns the name of a key (given by virtual key code) as a string.		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 one parameter (the virtual key code of the key that was pressed) 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.
		+
		+	''NOTE: The CTRL+ALT+DELETE keyboard combo cannot be blocked by a low-level keyboard hook. That is processed at the driver-level.''
		+
		+
		+	''Example''
		+	<source lang="lua">
		+	function hook(vk)
		+	-- If the user presses the Windows keys, ignore them completely
		+	-- Otherwise, let the keypress go through.
		+
		+	if( 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
		+	</source>

← Older revision		Revision as of 16:51, 12 April 2015
Line 28:		Line 28:
	print("Caps lock ?", keyboard.getToggleState(key.VK_CAPSLOCK));		print("Caps lock ?", keyboard.getToggleState(key.VK_CAPSLOCK));
	</source>		</source>
		+
		+
		+	== setToggleState ==
		+	'''keyboard.setToggleState(number vk, boolean status)'''
		+
		+	Sets the toggle state of a key to 'status'. true = on, false = off.

← Older revision		Revision as of 18:32, 14 November 2014
Line 75:		Line 75:

	Attempts to send a synthetic release for the given key, and sends that input directly to the given window.		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.

@@ Line 31: / Line 31: @@
 == press ==
-'''keyboard.press(number vk)'''
+'''keyboard.press(number vk[, bool async])'''
 Attempts to send a synthetic press for the given key.
@@ Line 37: / Line 37: @@
 This will send the input to whichever window has input focus at the time.
 == hold ==

← Older revision		Revision as of 23:34, 29 September 2014
Line 76:		Line 76:

	Attempts to send a synthetic release for the given key, and sends that input directly to the given window.		Attempts to send a synthetic release for the given key, and sends that input directly to the given window.
		+
		+
		+	== getKeyName ==
		+	'''string keyboard.getKeyName(number vk)'''
		+
		+	Returns the name of a key (given by virtual key code) as a string.

← Older revision	Revision as of 18:31, 3 June 2014
(No difference)