Hotkey

Creates, modifies, enables, or disables a hotkey while the script is running.

Hotkey, KeyName [, Label, Options]
Hotkey, IfWinActive/Exist [, WinTitle, WinText]

Parameters

ErrorLevel

ErrorLevel is changed only when: 1) the first parameter is IfWin[Not]Active/Exist, in which case it is set to 1 if there was a problem or 0 otherwise; or 2) the word UseErrorLevel is present in the Options parameter.

Tip: The UseErrorLevel option can be used to test for the existence of a hotkey variant. For example:

Hotkey, ^!p,, UseErrorLevel
if ErrorLevel in 5,6
    MsgBox The hotkey does not exist or it has no variant for the current IfWin criteria.

Remarks

If the goal is to disable selected hotkeys or hotstrings automatically based on the type of window that is active, Hotkey, ^!c, Off is usually less convenient than using #IfWinActive/Exist (or their dynamic counterparts "Hotkey IfWinActive/Exist" below).

Creating hotkeys via double-colon labels performs better than using the Hotkey command because the hotkeys can all be enabled as a batch when the script starts (rather than one by one). Therefore, it is best to use this command to create only those hotkeys whose key names are not known until after the script has started running. One such case is when a script's hotkeys for various actions are configurable via an INI file.

A given label can be the target of more than one hotkey. If it is known that a label was called by a hotkey, you can determine which hotkey by checking the built-in variable A_ThisHotkey.

If the script is suspended, newly added/enabled hotkeys will also be suspended until the suspension is turned off (unless they are exempt as described in the Suspend section).

The keyboard and/or mouse hooks will be installed or removed if justified by the changes made by this command.

Although the Hotkey command cannot directly enable or disable hotkeys in scripts other than its own, in most cases it can override them by creating or enabling the same hotkeys. Whether this works depends on a combination of factors: 1) Whether the hotkey to be overridden is a hook hotkey in the other script (non-hook hotkeys can always be overridden except on Win9x); 2) The fact that the most recently started script's hotkeys generally take precedence over those in other scripts (therefore, if the script intending to override was started most recently, its override should always succeed); 3) Whether the enabling or creating of this hotkey will newly activate the keyboard or mouse hook (if so, the override will always succeed).

Once a script has at least one hotkey, it becomes persistent, meaning that ExitApp rather than Exit should be used to terminate it. Hotkey scripts are also automatically #SingleInstance unless #SingleInstance Off has been specified.

Remarks About Hotkey, IfWinXX [, WinTitle, WinText]

In v1.0.42+, the "Hotkey IfWin" commands allow context-sensitive hotkeys to be created and modified while the script is running (by contrast, the #IfWinActive/Exist directives are positional and take effect before the script begins executing). For example:

Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!e, MyLabel  ; Creates a hotkey that works only in Notepad.

Using "Hotkey IfWin" puts context sensitivity into effect for all subsequently created or modified hotkeys. In addition, each IfWin sub-command is mutually exclusive; that is, only the most recent one will be in effect.

To turn off context sensitivity (that is, to make subsequently-created hotkeys work in all windows), specify any IfWin sub-command but omit the WinTitle/Text parameters. For example: Hotkey, IfWinActive

If "Hotkey IfWin" is never used by a script, the bottommost use of the #IfWin directive (if any) will be in effect for the Hotkey command.

When a mouse or keyboard hotkey is disabled via IfWin, it performs its native function; that is, it passes through to the active window as though there is no such hotkey. There are two exceptions: 1) Windows 95/98/Me: pressing an IfWin-disabled hotkey has no effect (not even its native function); and 2) Joystick hotkeys: although IfWin works, it never prevents other programs from seeing the press of a button.

Variant (Duplicate) Hotkeys [v1.0.42+]

A particular hotkey can be created more than once if each definition has different IfWin criteria. These are known as hotkey variants. For example:

Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!c, MyLabelForNotepad
Hotkey, IfWinActive, ahk_class WordPadClass
Hotkey, ^!c, MyLabelForWordPad
Hotkey, IfWinActive
Hotkey, ^!c, MyLabelForAllOtherWindows

If more than one variant of a hotkey is eligible to fire, only the one created earliest will fire. The exception to this is the global variant (the one with no IfWin criteria): It always has the lowest precedence, and thus will fire only if no other variant is eligible.

The order of modifier symbols such as ^!+# does not matter. For example, ^!c is the same as !^c. However, any hotkey with a wildcard prefix (*) is an entirely separate hotkey from a non-wildcard one (for example, *F1 and F1 would each have their own set of variants).

For more information about IfWin hotkeys, see #IfWin's General Remarks.

Related

Hotkey Symbols, #IfWinActive/Exist, #MaxThreadsBuffer, #MaxThreadsPerHotkey, Suspend, IsLabel(), Threads, Thread, Critical, Gosub, Return, Menu, SetTimer

Examples

Hotkey, ^!z, MyLabel
return

MyLabel:
MsgBox You pressed %A_ThisHotkey%.
return

; Other examples:
Hotkey, RCtrl & RShift, AltTab ; Makes RCtrl & RShift operate like Alt-Tab.
Hotkey, #c, On  ; Re-enables the Win-C hotkey.
Hotkey, $+#c, Off  ; Disables the Shift-Win-C hotkey.
Hotkey, ^!a, , T5  ; Changes the hotkey to allow 5 threads.

Hotkey, IfWinActive, ahk_class Notepad
Hotkey, ^!c, MyLabelForNotepad  ; Creates Ctrl-Alt-C as a hotkey that works only in Notepad.