# Labels

## Table of Contents

- Syntax and Usage
- Subroutines
- Dynamic Labels
- Hotkeys and Hotstrings
- Named Loops
- Functions
- Related

## Syntax and Usage

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:

- A hotkey label can be directly followed by a command or other statement to create a one-line hotkey. In other words, if a command, assignment or expression is present on the same line as a hotkey label, it acts as though followed by `return`.
- A hotkey with a key name written to the right of the double-colon is actually a remapping, which is shorthand for a pair of hotkeys. For example, `a::b` creates hotkeys and labels for `*a` and `*a Up`, and does not create a label named `a`.
- A hotstring with text written to the right of the final double-colon is an auto-replace hotstring. Auto-replace hotstrings do not act as labels.

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

## Subroutines

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.

## Dynamic Labels

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.

## Hotkeys and Hotstrings

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.

## Named Loops

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.

## Functions

[v1.1.20+]: Functions can be used in place of labels in a number of cases, including:

- Gui events such as GuiClose
- Gui control events (g-labels)
- Hotkey
- Menu
- SetTimer

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.

## Related

IsLabel(), A_ThisLabel, Gosub, Goto, OnExit, SetTimer, Hotkey, Gui Events, g-label, OnClipboardChange