Returns 1 (true) or 0 (false) depending on whether the specified keyboard key or mouse/controller button is down or up. Also retrieves controller status.
IsDown := GetKeyState(KeyName , Mode)
Type: String
This can be just about any single character from the keyboard or one of the key names from the key list, such as a mouse/controller button. Examples: B, 5, LWin, RControl, Alt, Enter, Escape, LButton, MButton, Joy1.
Alternatively, an explicit virtual key code such as vkFF may be specified. This is useful in the rare case where a key has no name. The code of such a key can be determined by following the steps at the bottom of the key list page. Note that this code must be in hexadecimal.
Known limitation: This function cannot differentiate between two keys which share the same virtual key code, such as Left and NumpadLeft.
This parameter is ignored when retrieving controller status.
If omitted, it defaults to that which retrieves the logical state of the key. This is the state that the OS and the active window believe the key to be in, but is not necessarily the same as the physical state.
Otherwise, specify one of the following letters, or a device identifier:
L: Retrieve the logical state, as when Mode is omitted.
P: Retrieve the physical state (i.e. whether the user is physically holding it down). The physical state of a key or mouse button will usually be the same as the logical state unless the keyboard and/or mouse hooks are installed, in which case it will accurately reflect whether or not the user is physically holding down the key or button (as long as it was pressed down while the keyboard hook was installed). You can determine if your script is using the hooks via the KeyHistory function or menu item. You can force the hooks to be installed by calling InstallKeybdHook and/or InstallMouseHook.
T: Retrieve the toggle state. For keys other than CapsLock, NumLock and ScrollLock, the toggle state is generally 0 when the script starts and is not synchronized between processes.
Device identifier: A positive integer, as reported by the DeviceId property of A_EventInfo in a hotkey, retrieves the physical state of that one input source. A device identifier always reads physical state. The identifier belongs to the broker process and must be refreshed after the service restarts; an unknown or disconnected identifier returns 0. Keypad names such as Numpad1 and NumpadEnd follow the NumLock and logical Shift state shared by all keyboards, as hotkeys do.
The letters query every source at once, and the logical state also includes generated input. Device identifiers are supported on Linux and require keysharp-input client ABI 1.0 or a newer 1.x minor version together with InputMonitoring permission, even for a modifier or lock key; the letters read modifier state and the toggle state (T) of lock keys without it. On Linux, an unavailable or incompatible input component makes the device-state query return 0; a refused InputMonitoring permission request raises an error. Windows and macOS raise a ValueError for a device identifier.
Type: Integer (boolean), Float, Integer or String (empty)
This function returns 1 (true) if the key is down (or toggled on) or 0 (false) if it is up (or toggled off).
When KeyName is a stick axis such as JoyX, this function returns a floating-point number between 0 and 100 to indicate the stick's position as a percentage of that axis's range of motion. This test script can be used to analyze your controller(s).
When KeyName is JoyPOV, this function returns an integer between 0 and 35900. The following approximate POV values are used by many controllers:
When KeyName is JoyName, JoyButtons, JoyAxes or JoyInfo, the retrieved value will be the name, number of buttons, number of axes or capabilities of the controller. For details, see Game Controller.
When KeyName is a button or control of a controller that could not be detected, this function returns an empty string.
A ValueError is thrown if invalid parameters are detected, e.g. when KeyName does not exist on the script's current keyboard layout, or Mode does not begin with L, P or T and is not a device identifier from 1 to 4294967295. An ASCII letter A-Z without a layout mapping uses the corresponding virtual key, as with GetKeyVK.
Except for modifier state and the toggle state of lock keys, polling a key or mouse button can require the InputMonitoring capability.
To wait for a key or mouse/controller button to achieve a new state, it is usually easier to use KeyWait instead of a GetKeyState loop.
Systems with unusual keyboard drivers might be slow to update the state of their keys, especially the toggle-state of keys like CapsLock. A script that checks the state of such a key immediately after it changed may use Sleep beforehand to give the system time to update the key state.
For examples of using GetKeyState with a controller, see the controller remapping page and the Controller-To-Mouse script.
Physical key and button state is tracked separately for each source by keysharp-input. Without a device identifier, releasing a key on one keyboard does not clear another keyboard's hold. This applies even while keyboard or mouse hooks are installed; polling does not install a hook. When keysharp-input cannot answer a physical query, P retrieves the logical state instead.
While keysharp-input intercepts a keyboard, a physical key-up that reaches the desktop also releases the key where a script's Send is holding it down, as on Windows. A key-up that a hotkey suppresses leaves the hold in place; for example, with w::Send "{w down}", W stays down after it is released.
A source can be the output of an upstream remapper such as keyd. Its identifier and state describe that input stream, not the hardware devices merged by the upstream remapper. Logical state describes the broker's output and can be transformed further by downstream software.
GetKeyVK, GetKeySC, GetKeyName, KeyWait, Key List, Controller remapping, KeyHistory, InstallKeybdHook, InstallMouseHook
Checks if at least one Shift is down.
if GetKeyState("Shift")
MsgBox "At least one Shift key is down."
else
MsgBox "Neither Shift key is down."
On Linux, reads the left Shift key on the keyboard that triggered the hotkey. Requires keysharp-input client ABI 1.0 or a newer 1.x minor version and the input permissions required by hotkeys.
F8::
{
DeviceID := A_EventInfo.DeviceId
if DeviceID > 0
OutputDebug GetKeyState("LShift", DeviceID)
}
Remapping. (This example is only for illustration because it would be easier to use the built-in remapping feature.) In the following hotkey, the mouse button is kept held down while NumpadAdd is down, which effectively transforms NumpadAdd into a mouse button. This method can also be used to repeat an action while the user is holding down a key or button.
*NumpadAdd::
{
MouseClick "left",,, 1, 0, "D" ; Hold down the left mouse button.
Loop
{
Sleep 10
if !GetKeyState("NumpadAdd", "P") ; The key has been released, so break out of the loop.
break
; ... insert here any other actions you want repeated.
}
MouseClick "left",,, 1, 0, "U" ; Release the mouse button.
}
Makes controller button behavior depend on stick axis position.
joy2::
{
JoyX := GetKeyState("JoyX")
if JoyX > 75
MsgBox "Action #1 (button pressed while stick was pushed to the right)."
else if JoyX < 25
MsgBox "Action #2 (button pressed while stick was pushed to the left)."
else
MsgBox "Action #3 (button pressed while stick was centered horizontally)."
}
See the controller remapping page and the Controller-To-Mouse script for other examples.