GetKeyState

GetKeyState can be used as a function or command, although the former is recommended for new scripts. Both check whether a keyboard key or mouse/controller button is down or up, and also retrieve controller status. The difference is that the function can be used in an expression and returns 1 (true) for down or 0 (false) for up, while the command stores D for down or U for up in a variable.

GetKeyState Function

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.

KeyIsDown := GetKeyState(KeyName , Mode)

Parameters

KeyName

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 virtual key code of such a key can be determined by following the steps at the bottom of the key list page.

Known limitation: This function cannot differentiate between two keys which share the same virtual key code, such as Left and NumpadLeft.

Mode

This parameter is ignored when retrieving controller status.

If blank or 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:

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 script was running). You can determine if your script is using the hooks via the KeyHistory command or menu item. You can force the hooks to be installed by adding the #InstallKeybdHook and/or #InstallMouseHook directives to the script.

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.

Return Value

This function returns 1 (true) if the key is down (or toggled on) or 0 (false) if it is up (or toggled off). For the controller's special controls such as axes and POV switch, other values are retrieved.

If KeyName is invalid or the state of the key could not be determined, an empty string is returned.

GetKeyState Command

Stores the letter D or U in a variable depending on whether the specified keyboard key or mouse/controller button is down or up. Also retrieves controller status.

Deprecated: This command is not recommended for use in new scripts. Use the GetKeyState function described above instead.

GetKeyState, OutputVar, KeyName , Mode

Parameters

OutputVar

The name of the output variable in which to store the retrieved key state, which is either D for down or U for up. The variable will be empty (blank) if the state of the key could not be determined. For the controller's special controls such as axes and POV switch, other values are retrieved.

KeyName

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 virtual key code of such a key can be determined by following the steps at the bottom of the key list page.

Known limitation: This command cannot differentiate between two keys which share the same virtual key code, such as Left and NumpadLeft.

Mode

This parameter is ignored when retrieving controller status.

If blank or 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:

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 script was running). You can determine if your script is using the hooks via the KeyHistory command or menu item. You can force the hooks to be installed by adding the #InstallKeybdHook and/or #InstallMouseHook directives to the script.

T: Retrieve the toggle state. A retrieved value of D means the key is "on", while U means it's "off". For keys other than CapsLock, NumLock and ScrollLock, the toggle state is generally U when the script starts and is not synchronized between processes.

Controller's Special Controls

When KeyName is a stick axis such as JoyX, the retrieved value will be a floating point number between 0 and 100 to indicate the stick's position as a percentage of that axis's range of motion. The format of the number can be changed via Format() or SetFormat. This test script can be used to analyze your controller(s).

When KeyName is JoyPOV, the retrieved value will be 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.

Remarks

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.

KeyWait, Key List, Controller remapping, KeyHistory, #InstallKeybdHook, #InstallMouseHook

Examples

Function vs. command. Although the first code block uses the function and the second uses the command, these two blocks are functionally identical.

state := GetKeyState("RButton")  ; Right mouse button.
state := GetKeyState("Joy2")  ; The second button of the first controller.

if GetKeyState("Shift")
    MsgBox At least one Shift key is down.
else
    MsgBox Neither Shift key is down.

state := GetKeyState("CapsLock", "T") ; True if CapsLock is ON, false otherwise.
GetKeyState, state, RButton  ; Right mouse button.
GetKeyState, state, Joy2  ; The second button of the first controller.

GetKeyState, state, Shift
if (state = "D")
    MsgBox At least one Shift key is down.
else
    MsgBox Neither Shift key is down.

GetKeyState, state, CapsLock, T ;  D if CapsLock is ON or U otherwise.

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

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

See the controller remapping page and the Controller-To-Mouse script for other examples.