# Input

Waits for the user to type a string (not supported on Windows 9x: it does nothing).

Input [, OutputVar, Options, EndKeys, MatchList]

#### Parameters

OutputVar | The name of the variable in which to store the text entered by the user (by default, artificial input is also captured). If this and the other parameters are omitted, any Input in progress in another thread is terminated and its ErrorLevel is set to the word NewInput. By contrast, the ErrorLevel of the current command will be set to 0 if it terminated a prior Input, or 1 if there was no prior Input to terminate. OutputVar does not store keystrokes per se. Instead, it stores characters produced by keystrokes according to the active window's keyboard layout/language. Consequently, keystrokes that do not produce characters (such as PageUp and Escape) are not stored (though they can be recognized via the EndKeys parameter below). Whitespace characters such as TAB (`t) are stored literally. ENTER is stored as linefeed (`n).
Options | A string of zero or more of the following letters (in any order, with optional spaces in between): B: Backspace is ignored. Normally, pressing backspace during an Input will remove the most recently pressed character from the end of the string. Note: If the input text is visible (such as in an editor) and the arrow keys or other means are used to navigate within it, backspace will still remove the last character rather than the one behind the caret (insertion point). C: Case sensitive. Normally, MatchList is not case sensitive (in versions prior to 1.0.43.03, only the letters A-Z are recognized as having varying case, not letters like ü/Ü). I: Ignore input generated by any AutoHotkey script, such as the SendEvent command. However, the SendInput and SendPlay methods are always ignored, regardless of this setting. L: Length limit (e.g. L5). The maximum allowed length of the input. When the text reaches this length, the Input will be terminated and ErrorLevel will be set to the word Max unless the text matches one of the MatchList phrases, in which case ErrorLevel is set to the word Match. If unspecified, the length limit is 16383, which is also the absolute maximum. M: Modified keystrokes such as Control-A through Control-Z are recognized and transcribed if they correspond to real ASCII characters. Consider this example, which recognizes Control-C:
    Transform, CtrlC, Chr, 3 ; Store the character for Ctrl-C in the CtrlC var.
    Input, OutputVar, L1 M
    if OutputVar = %CtrlC%
        MsgBox, You pressed Control-C.
    ExitApp
Note: The characters Ctrl-A through Ctrl-Z correspond to Chr(1) through Chr(26). Also, the M option might cause some keyboard shortcuts such as Ctrl-LeftArrow to misbehave while an Input is in progress. T: Timeout (e.g. T3). The number of seconds to wait before terminating the Input and setting ErrorLevel to the word Timeout. If the Input times out, OutputVar will be set to whatever text the user had time to enter. This value can be a floating point number such as 2.5. V: Visible. Normally, the user's input is blocked (hidden from the system). Use this option to have the user's keystrokes sent to the active window. *: Wildcard (find anywhere). Normally, what the user types must exactly match one of the MatchList phrases for a match to occur. Use this option to find a match more often by searching the entire length of the input text.
EndKeys | A list of zero or more keys, any one of which terminates the Input when pressed (the EndKey itself is not written to OutputVar). When an Input is terminated this way, ErrorLevel is set to the word EndKey followed by a colon and the name of the EndKey. Examples: EndKey:. EndKey:Escape The EndKey list uses a format similar to the Send command. For example, specifying {Enter}.{Esc} would cause either ENTER, period (.), or ESCAPE to terminate the Input. To use the braces themselves as end keys, specify {{} and/or {}}. To use Control, Alt, or Shift as end-keys, specify the left and/or right version of the key, not the neutral version. For example, specify {LControl}{RControl} rather than {Control}. Although modified keys such as Control-C (^c) are not supported, certain keys that require the shift key to be held down -- namely punctuation marks such as ?!:@&{} -- are supported in v1.0.14+. An explicit virtual key code such as {vkFF} may also be specified. This is useful in the rare case where a key has no name and produces no visible character when pressed. Its virtual key code can be determined by following the steps at the bottom fo the key list page.
MatchList | A comma-separated list of key phrases, any of which will cause the Input to be terminated (in which case ErrorLevel will be set to the word Match). The entirety of what the user types must exactly match one of the phrases for a match to occur (unless the * option is present). In addition, any spaces or tabs around the delimiting commas are significant, meaning that they are part of the match string. For example, if MatchList is "ABC , XYZ ", the user must type a space after ABC or before XYZ to cause a match. Two consecutive commas results in a single literal comma. For example, the following would produce a single literal comma at the end of string: "string1,,,string2". Similarly, the following list contains only a single item with a literal comma inside it: "single,,item". Because the items in MatchList are not treated as individual parameters, the list can be contained entirely within a variable. In fact, all or part of it must be contained in a variable if its length exceeds 16383 since that is the maximum length of any script line. For example, MatchList might consist of %List1%,%List2%,%List3% -- where each of the variables contains a large sub-list of match phrases.

#### ErrorLevel

1 or 0 | Whenever the command is used without parameters, ErrorLevel is set to 0 if it successfully terminates a prior input, or 1 if there is no Input in progress.
NewInput | The Input was interrupted by another thread that used the Input command.
Max | The Input reached the maximum allowed length and it does not match any of the items in MatchList.
Timeout | The Input timed out.
Match | The Input matches one of the items in MatchList.
EndKey:name | One of the EndKeys was pressed to terminate the Input. In this case, ErrorLevel contains the word EndKey followed by a colon and the name of the terminating key without braces, e.g. EndKey:Enter, EndKey:Escape, etc.

#### Remarks

If this command is used while an Input is already in progress in another thread, that Input will be terminated and its ErrorLevel will be set to the word NewInput. After that (if parameters were given), the new Input will commence.

While an Input is in progress, new threads such as custom menu items and timed subroutines can still be created. Similarly, keyboard hotkeys are still in effect if the Input is visible. If the Input is not visible, only hook hotkeys can be triggered.

When a script first uses this command, the keyboard hook is installed (if it is not already). In addition, the script becomes persistent, meaning that ExitApp should be used to terminate it. The keyboard hook will stay installed until the next use of the Suspend or Hotkey command, at which time it is removed if not required by any hotkeys or hotstrings.

If you use multiple languages or keyboard layouts, Input uses the keyboard layout of the active window rather than the script's (regardless of whether the Input is visible). However, in versions prior to 1.0.44.03, the script's own layout is used.

Although not as flexible, hotstrings are generally easier to use than the Input command.

Input does nothing on Windows 9x (not even changing ErrorLevel and OutputVar). To detect Windows 9x, use A_OSType.

#### Related

KeyWait, Hotstrings, InputBox, #InstallKeybdHook, Threads, if var in/contains MatchList

#### Examples

    ; Wait for the user to press any key.  Keys that produce no visible character -- such as
    ; the modifier keys, function keys, and arrow keys -- are listed as end keys so that they
    ; will be detected too.
    Input, SingleKey, L1, {LControl}{RControl}{LAlt}{RAlt}{LShift}{RShift}{LWin}{RWin}{AppsKey}{F1}{F2}{F3}{F4}{F5}{F6}{F7}{F8}{F9}{F10}{F11}{F12}{Left}{Right}{Up}{Down}{Home}{End}{PgUp}{PgDn}{Del}{Ins}{BS}{Capslock}{Numlock}{PrintScreen}{Pause}

    ; This is a working hotkey example.  Since the hotkey has the tilde (~)
    ; prefix, its own keystroke will pass through to the active window
    ; (except on Win9x).  Thus, if you type [btw (or one of the other match
    ; phrases) in any editor, the script will automatically perform an
    ; action of your choice (such as replacing the typed text):

    ~[::
    Input, UserInput, V T5 L4 C, {enter}.{esc}{tab}, btw,otoh,fl,ahk,ca
    if ErrorLevel = Max
    {
        MsgBox, You entered "%UserInput%", which is the maximum length of text.
        return
    }
    if ErrorLevel = Timeout
    {
        MsgBox, You entered "%UserInput%" at which time the input timed out.
        return
    }
    if ErrorLevel = NewInput
        return
    IfInString, ErrorLevel, EndKey:
    {
        MsgBox, You entered "%UserInput%" and terminated the input with %ErrorLevel%.
        return
    }
    ; Otherwise, a match was found.
    SetKeyDelay, -1  ; Most editors can handle the fastest speed.
    if UserInput = btw
        Send, {backspace 4}by the way
    else if UserInput = otoh
        Send, {backspace 5}on the other hand
    else if UserInput = fl
        Send, {backspace 3}Florida
    else if UserInput = ca
        Send, {backspace 3}California
    else if UserInput = ahk
        Run, www.autohotkey.com
    return