A label identifies a line of code, and can be used as a Goto target or to form a subroutine. There are three kinds of label: normal named labels, hotkey labels and hotstring labels.
Normal labels consist of a name followed by a colon.
this_is_a_label:
Hotkey labels consist of a hotkey followed by double-colon.
^a::
Hotstring labels consist of a colon, zero or more options, another colon, an abbreviation and double-colon.
:*:btw::
Generally, aside from whitespace and comments, no other code can be written on the same line as a label. However:
return.a::b creates hotkeys and labels for *a and *a Up, and does not create a label named a.Names: Label names are not case sensitive, and may consist of any characters other than space, tab, comma and the escape character (`). However, due to style conventions, it is generally better to use only letters, numbers, and the underscore character (for example: MyListView, Menu_File_Open, and outer_loop). Label names must be unique throughout the whole script.
Although there are no reserved names, it is strongly recommended that the following names not be used: On, Off, Toggle, AltTab, ShiftAltTab, AltTabAndMenu and AltTabMenuDismiss. These values have special meaning to the Hotkey command.
Target: The target of a label is the next line of executable code. Executable code includes commands, assignments, expressions and blocks, but not directives, labels, hotkeys or hotstrings. In the following example, run_notepad and #n both point at the Run line:
run_notepad:
#n::
Run Notepad
return
Execution: Like directives, labels have no effect when reached during normal execution. In the following example, a message box is shown twice - once during execution of the subroutine by Gosub, and again after the subroutine returns:
gosub Label1 Label1: MsgBox %A_ThisLabel% return
A subroutine is a portion of code which can be called to perform a specific task. Execution of a subroutine begins at the target of a label and continues until a Return or Exit is encountered. Since the end of a subroutine depends on flow of control, any label can act as both a Goto target and the beginning of a subroutine.
Many commands which accept a label name also accept a variable reference such as %MyLabel%, in which case the name stored in the variable is used as the target. However, performance is slightly reduced because the target label must be "looked up" each time rather than only once when the script is first loaded.
Each double-colon hotkey also creates a label, unless it is a function hotkey. The label's name is exactly as written in the script, and can differ from the hotkey's name as reported by A_ThisHotkey, such as if the modifiers are written in a different order. The label name includes the hotkey's modifiers but not the final double-colon (::).
A hotstring label's name includes the leading colon and options, but not the final double-colon (::).
Hotkey and hotstring labels are also valid targets for Goto, Gosub and other commands. However, a hotkey or hotstring label can only be used in this manner if it is the first label with the given name. For example:
gosub ^+a ; Example hotkey.
gosub +^a ; Global hotkey.
gosub Esc ; Esc label.
ExitApp
#IfWinActive Example
^+a::MsgBox Example hotkey.
Esc:
MsgBox Esc label.
return
#If
+^a::MsgBox Global hotkey.
Esc::MsgBox Esc hotkey.
This limitation also applies to the Hotkey command's Label parameter.
A label can also be used to identify a loop for the Continue and Break commands. This allows the script to easily continue or break out of any number of nested loops.
[v1.1.20+]: Functions can be used in place of labels in a number of cases, including:
The benefits of functions are that they can use local variables, and in some cases (such as Gui control events) they also accept parameters containing useful information.
IsLabel(), A_ThisLabel, Gosub, Goto, OnExit, SetTimer, Hotkey, Gui Events, g-label, OnClipboardChange Label