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.
Hotkey labels consist of a hotkey followed by double-colon.
Hotstring labels consist of a colon, zero or more options, another colon, an abbreviation and double-colon.
Generally, aside from whitespace and comments, no other code can be written on the same line as a label. However:
a::bcreates hotkeys and labels for
*a Up, and does not create a label named
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,
#n both point at the
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.
Hotkey and hotstring labels are also valid targets for Goto, Gosub and other commands. However, if a hotkey or hotstring has multiple variants, the variant closest to the top of the script is used. All of the hotkey's modifiers or hotstring's options are also part of its label name, but the final double-colon (::) is omitted.
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