Input

Waits for the user to type a string.

Text := Input(Options, EndKeys, MatchList)

Parameters

Text (return value)

The text entered by the user (by default, artificial input is also captured).

The text consists of 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.

I: Ignore input generated by any AutoHotkey script, such as the SendEvent function. 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:

CtrlC := Chr(3) ; Store the character for Ctrl-C in the CtrlC var.
OutputVar := Input("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.

E: 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 function. 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 characters that require the shift key to be held down -- namely punctuation marks such as ?!:@&{} -- are supported. Other characters are supported with the E option described above.

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 be the expression List1 "," List2 "," List3 -- where each of the variables contains a large sub-list of match phrases.

ErrorLevel

NewInput	The Input was terminated by another thread calling the Input function.
End	The Input was terminated by another thread calling the InputEnd function.
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 "ErrorLevel: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. Single-character key names without the E option are usually lower-case, since the shift state is ignored.

Remarks

If this function 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 function, the keyboard hook is installed (if it is not already). The keyboard hook will stay installed until the next use of the Suspend or Hotkey function, 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).

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

InputEnd

Terminates any Input in progress in another thread.

InputEnd

Returns true if an Input was in progress, otherwise false.

KeyWait, Hotstrings, InputBox, #InstallKeybdHook, Threads

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.
SingleChar := Input("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}")
if InStr(ErrorLevel, "EndKey:")
    SingleKey := SubStr(ErrorLevel, 8)
else
    SingleKey := SingleChar
MsgBox SingleKey