Creates, modifies, enables, or disables a hotkey while the script is running.
| Hotkey, KeyName [, Label, Options] |
Parameters
| KeyName | Name of the hotkey's activation key, including any modifier symbols. For example, specify #c for the Win+C hotkey. If KeyName already exists as a hotkey, that hotkey will be updated with the values of the other parameters below. For this purpose, KeyName is not case sensitive. KeyName can also be the name of an existing hotkey label (i.e. a double-colon label), which will cause that hotkey to be updated with the values of the other parameters below. When specifying an existing hotkey, the order of the modifier symbols must match the order used when the hotkey was created. For example, ^!c is not the same as !^c for matching purposes. |
| Label | The label name whose contents will be executed (as a new thread) when the hotkey is pressed. Both normal labels and hotkey/hotstring labels can be used. The trailing colon(s) should not be included. If Label is dynamic (e.g. %VarContainingLabelName%), IsLabel() may be called to verify that the label exists. This parameter can be left blank if KeyName already exists as a hotkey, in which case its label will not be changed. This is done to change the hotkey's Options without changing its label. If the label is specified but the hotkey is disabled from a previous use of this command, the hotkey will still be disabled afterward. To turn it on, use "Hotkey, KeyName, On" immediately afterward (or in v1.0.38.02+, include the word On in Options). This parameter can also be one of the following special values: On: The hotkey is enabled. No action is taken if the hotkey is already On. Off: The hotkey is disabled. No action is taken if the hotkey is already Off. Toggle: The hotkey is set to the opposite state (enabled or disabled). AltTab (and others): These are special Alt-Tab hotkey actions that are described here. |
| Options | A string of zero or more of the following letters with optional spaces in between. For example: On B0 T5 On [v1.0.38.02+]: The word On enables the hotkey if it is currently disabled. B or B0: Specify the letter B to buffer the hotkey as described in #MaxThreadsBuffer. Specify B0 (B with the number 0) to disable this type of buffering. Pn: Specify the letter P followed by the hotkey's thread priority. If the P option is omitted when creating a hotkey, 0 will be used. Tn: Specify the letter T followed by a the number of threads to allow for this hotkey as described in #MaxThreadsPerHotkey. For example: T5 If either or both of the B and T option letters are omitted and the hotkey already exists, those options will not be changed. But if the hotkey does not yet exist -- that is, it is about to be created by this command -- the options will default to those most recently in effect. For example, the instance of #MaxThreadsBuffer that occurs closest to the bottom of the script will be used. If #MaxThreadsBuffer does not appear in the script, its default setting (OFF in this case) will be used. |
Remarks
Creating hotkeys via double-colon labels performs better than using this command because the hotkeys can all be enabled as a batch (rather than one by one) when the script starts. 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.
Related
Hotkey Symbols, #MaxThreadsBuffer, #MaxThreadsPerHotkey, Suspend, IsLabel(), Threads, Thread, Critical, Gosub, Return, Menu, SetTimer
Examples
Hotkey, ^!z, MyLabel
return
MyLabel:
MsgBox You pressed %A_ThisHotkey%.
return
Hotkey, RCtrl & RShift, AltTab ; Makes RCtrl & RShift operate like Alt-Tab.
Hotkey, #c, On
Hotkey, $+#c, Off
Hotkey, ^!a, , T5 ; Change the hotkey to allow 5 threads.