Input

Waits for the user to type a string.

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 PgUp and Home) are not stored (though they can be recognized via the EndKeys parameter below).

Note: Esc is translated to the ASCII ESC character, Chr(27). This can be avoided by including {Esc} in EndKeys, in which case pressing Esc will terminate Input.

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 the SendEvent method if it has a send level of 0. However, the SendInput and SendPlay methods are always ignored, regardless of this setting. [v1.1.31+]: The option letter can be followed by a number to set the minimum send level. I and I1 are equivalent, and I0 is the same as not specifying the option.

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 in versions prior to [v1.1.31].

M: Modified keystrokes such as Ctrl+A through Ctrl+Z are recognized and transcribed if they correspond to real ASCII characters. Consider this example, which recognizes Ctrl+C:

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+← 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.

E [v1.1.20+]: Handle single-character end keys by character code instead of by keycode. This provides more consistent results if the active window's keyboard layout is different to the script's keyboard layout. It also prevents key combinations which don't actually produce the given end characters from ending input; for example, if @ is an end key, on the US layout Shift+2 will trigger it but Ctrl+Shift+2 will not (if the E option is used). If the C option is also used, the end character is case-sensitive.

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, ., or Esc to terminate the Input. To use the braces themselves as end keys, specify {{} and/or {}}.

To use Ctrl, 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}.

[v1.0.14+]: Although modified keys such as Alt+C (!c) are not supported, certain characters that require Shift to be held down -- namely punctuation marks such as ?!:@&{} -- are supported. [v1.1.20+]: Other characters are supported with the E option described above. When the E and M options are both used, Ctrl+A through Ctrl+Z are supported by including the corresponding ASCII control characters in EndKeys.

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.

Error Handling

[v1.1.04+]: This command is able to throw an exception if called with no parameters and there is no Input in progress. For more information, see Runtime Errors.

ErrorLevel is set to one of the following values:

Value Description

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.

Note that Name is the "normalized" name of the key regardless of how it was written in EndKeys. For example, {Esc} and {vk1B} both produce EndKey:Escape. GetKeyName() can be used to retrieve the normalized name.

If the E option was used, Name is the actual character which was typed (if applicable). Otherwise, the key name is determined according to the script's active keyboard layout.

Prior to [v1.1.20], if the VK code of the end key was in the range 0x41 (A) through 0x5A (Z), ErrorLevel usually contained the corresponding ASCII character even if that wasn't correct for the current keyboard layout. In [v1.1.20] and later, the correct character is used. If a character in the range A through Z is used, it is upper-case for backward-compatibility; otherwise it is usually lower-case.

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.

Keyboard hotkeys are still in effect while an Input is in progress, but cannot be triggered if any of the required modifier keys are suppressed, or if the hotkey uses the reg method and its suffix key is suppressed. For example, the hotkey ^+a:: might be overridden by Input, whereas $^+a:: would take precedence over Input.

If the Input is not visible, all keys are suppressed except the standard modifier keys, CapsLock, NumLock and ScrollLock. Even EndKeys and keystrokes which do not alter OutputVar are suppressed. For example, Home has no effect while LWin+D opens the Start menu (since D is suppressed but LWin is not).

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.

InputHook() is more flexible than the Input command.

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

Examples

Waits 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. 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). For an alternative version of this example, see Switch.

~[::
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
If InStr(ErrorLevel, "EndKey:")
{
    MsgBox, You entered "%UserInput%" and terminated the input with %ErrorLevel%.
    return
}
; Otherwise, a match was found.
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, https://www.autohotkey.com
return