# Hotkey

O comando Hotkey cria, modifica, habilita ou desabilita uma hotkey enquanto o script estiver em execução.

    Hotkey, KeyName , Label, Options
    Hotkey, IfWinActive/Exist , WinTitle, WinText
    Hotkey, If , Expression
    Hotkey, If, % FunctionObject

## Parâmetros

KeyName

  Nome da tecla de ativação da hotkey, incluindo quaisquer símbolos modificadores. Por exemplo, especifique `#c` para a hotkey `Win`+`C`.

  Se KeyName já existir como hotkey, aquela hotkey será atualizada com os valores de outros parâmetros do comando.

  KeyName também pode ser o nome de uma hotkey label existente (por exemplo, uma label de dois-pontos), o que faria com aquela hotkey ser atualizada com os valores de outros parâmetros do comando.

  Quando se especifica uma hotkey existente, KeyName não é case sensitive. Entretanto, os nomes das teclas devem ser digitadas exatamente a mesma forma que a hotkey existente (por exemplo, Esc não é o mesmo que Escape por esse motivo). Além disso, a ordem dos símbolos modificadores como ^!+# não importa. GetKeyName() pode ser usado para recuperar a forma de escrita padrão do nome de uma tecla.

  When a hotkey is first created -- either by the Hotkey command or a double-colon label in the script -- its key name and the ordering of its modifier symbols becomes the permanent name of that hotkey as reflected by A_ThisHotkey. This name is shared by all variants of the hotkey, and does not change even if the Hotkey command later accesses the hotkey with a different symbol ordering.

  [v1.1.15+]: If the hotkey variant already exists, its behavior is updated according to whether KeyName includes or excludes the tilde (~) prefix. However, prior to [v1.1.19], the hotkey was not updated if Label was omitted.

  [v1.1.19+]: The use hook ($) prefix can be added to existing hotkeys. This prefix affects all variants of the hotkey and cannot be removed. Prior to [v1.1.19], the prefix was ignored when modifying an existing hotkey variant.

Label

  The name of the label 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(VarContainingLabelName) may be called beforehand to verify that the label exists.

  [v1.1.20+]: If not a valid label name, this parameter can be the name of a function, or a single variable reference containing a function object. For example, `Hotkey %FuncObj%, On` or `Hotkey % FuncObj, On`. Other expressions which return objects are currently unsupported. When the hotkey executes, the function is called without parameters. Hotkeys can also be defined as functions without the Hotkey command.

  This parameter can be left blank if KeyName already exists as a hotkey, in which case its label will not be changed. This is useful to change only the hotkey's Options.

  Note: If the label or function is specified but the hotkey is disabled from a previous use of this command, the hotkey will remain disabled. To prevent this, include the word ON in Options.

  This parameter can also be one of the following special values:

  On: The hotkey becomes enabled. No action is taken if the hotkey is already On.

  Off: The hotkey becomes 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.

  Caution: Defining a label named On, Off, Toggle or AltTab (or any variation recognized by this command) may cause inconsistent behavior. It is strongly recommended that these values not be used as label names.

Options

  A string of zero or more of the following letters with optional spaces in between. For example: `UseErrorLevel B0`.

  UseErrorLevel: If the command encounters a problem, this option skips the warning dialog, sets ErrorLevel to one of the codes from the table below, then allows the current thread to continue.

  On: Enables the hotkey if it is currently disabled.

  Off: Disables the hotkey if it is currently enabled. This is typically used to create a hotkey in an initially-disabled state.

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

  In (InputLevel) [v1.1.23+]: Specify the letter I (or i) followed by the hotkey's input level. For example: `I1`.

  If any of the 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. This behavior also applies to #IfWin: the bottommost occurrence applies to newly created hotkeys unless "Hotkey IfWin" has executed since the script started.

IfWinActive
IfWinExist
IfWinNotActive
IfWinNotExist
If, Expression
If, % FunctionObject

  These sub-commands make all subsequently-created hotkeys context sensitive. See below for details.

WinTitle
WinText

  Within these parameters, any variable reference such as %var% becomes permanent the moment the command finishes. In other words, subsequent changes to the contents of the variable are not seen by existing IfWin hotkeys.

  Like #IfWinActive/Exist, WinTitle and WinText use the default settings for SetTitleMatchMode and DetectHiddenWindows as set in the auto-execute section. See #IfWinActive/Exist for details.

If, Expression

  [AHK_L 4+]: Associates subsequently-created hotkeys with a given #If expression. Expression must be an expression which has been used with the #If directive elsewhere in the script. Although this command is unable to create new expressions, it can create new hotkeys using an existing expression. See #If example 4.

  Note: The Hotkey command uses the string that you pass to it, not the original source code. Commas and deref chars (percent signs) are interpreted before the command is called, so may need to be escaped if they are part of the original expression. Escape sequences are resolved when the script loads, so only the resulting characters are considered; for example, `Hotkey, If, x = "`t"` and `Hotkey, If, % "x = """ A_Tab """"` both correspond to `#If x = "`t"`.

  Known limitation: If Expression contains an `and`/`or` operator, it is not recognized as an existing expression. As a workaround, use the equivalent `&&`/`||` operator in both the original #If expression and the one passed to the Hotkey command.

If, % FunctionObject

  [v1.1.25+]: Associates subsequently-created hotkeys with a given function object. Such hotkeys will only execute if calling the given function object yields a non-zero number. This is like `Hotkey, If, Expression`, except that each hotkey can have many variants (one per object). FunctionObject must be a single variable (not an expression) containing an object with a call method. The function or call method can accept one parameter, the name of the hotkey.

  Once passed to the Hotkey command, the object will never be deleted (but memory will be reclaimed by the OS when the process exits).

  The "three-key combination" example below uses this sub-command.

## Error Handling

[v1.1.04+]: This command is able to throw an exception on failure. For more information, see Runtime Errors.

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.

[v1.1.25+]: If the first parameter is "If", an exception is thrown if the second parameter is invalid or a memory allocation fails. ErrorLevel is not set in those cases, but is still set to 0 on success.

Error | Description
--- | ---
1 | The Label parameter specifies a nonexistent label name.
2 | The KeyName parameter specifies one or more keys that are either not recognized or not supported by the current keyboard layout/language.
3 | Unsupported prefix key. For example, using the mouse wheel as a prefix in a hotkey such as `WheelDown & Enter` is not supported.
4 | The KeyName parameter is not suitable for use with the AltTab or ShiftAltTab actions. A combination of two keys is required. For example: `RControl & RShift::AltTab`.
5 | The command attempted to modify a nonexistent hotkey.
6 | The command attempted to modify a nonexistent variant of an existing hotkey. To solve this, use Hotkey IfWin to set the criteria to match those of the hotkey to be modified.
98 | Creating this hotkey would exceed the limit of hotkeys per script (however, each hotkey can have an unlimited number of variants, and there is no limit to the number of hotstrings). The limit was raised from 700 to 1000 in [v1.0.48], and to 32762 in [v1.1.30].
99 | Out of memory. This is very rare and usually happens only when the operating system has become unstable.

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

    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

The current IfWin setting determines the variant of a hotkey upon which the Hotkey command will operate.

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); 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, If

The "Hotkey If" commands allow context-sensitive hotkeys to be created and modified while the script is running (by contrast, the #If and #IfWinActive/Exist directives are positional and take effect before the script begins executing). Por exemplo:

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

Using "Hotkey If" puts context sensitivity into effect for all subsequently created or modified hotkeys. In addition, each If 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 If sub-command but omit the parameters. For example: `Hotkey, If` or `Hotkey, IfWinActive`.

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

When a mouse or keyboard hotkey is disabled via an If sub-command or directive, it performs its native function; that is, it passes through to the active window as though there is no such hotkey. However, joystick hotkeys always pass through, whether they are disabled or not.

## Variant (Duplicate) Hotkeys

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

    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.

When creating duplicate hotkeys, the order of modifier symbols such as ^!+# does not matter. For example, `^!c` is the same as `!^c`. However, keys must be spelled consistently. For example, Esc is not the same as Escape for this purpose (though the case does not matter). Finally, any hotkey with a wildcard prefix (*) is entirely separate 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.

## Relacionado

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

## Exemplos

#1

    Hotkey, ^!z, MyLabel
    return

    MyLabel:
    MsgBox You pressed %A_ThisHotkey%.
    return

#2: 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.

#3: This GUI allows you to register primitive three-key combination hotkeys:

    Gui Add, Text, xm, Prefix key:
    Gui Add, Edit, yp x100 w100 vPrefix, Space
    Gui Add, Text, xm, Suffix hotkey:
    Gui Add, Edit, yp x100 w100  vSuffix, f & j
    Gui Add, Button, Default, Register
    Gui Show
    return

    ButtonRegister() {
        global
        Gui Submit, NoHide
        local fn
        fn := Func("HotkeyShouldFire").Bind(Prefix)
        Hotkey If, % fn
        Hotkey % Suffix, FireHotkey
    }

    HotkeyShouldFire(prefix, thisHotkey) {
        return GetKeyState(prefix)
    }

    FireHotkey() {
        MsgBox %A_ThisHotkey%
    }

    GuiClose:
    GuiEscape:
    ExitApp