PageRenderTime 27ms CodeModel.GetById 18ms RepoModel.GetById 0ms app.codeStats 0ms

/AutoHotkey.docset/Contents/Resources/Documents/commands/Input.htm

https://gitlab.com/ahkscript/Autohotkey.docset
HTML | 147 lines | 136 code | 11 blank | 0 comment | 0 complexity | 9a7a3a73b64b4bb3f2d776b9b8d85d82 MD5 | raw file
    

  1. <!DOCTYPE HTML>
    2. 

  2. <html>
    3. 

  3. <head>
    4. 

  4. <title>Input</title>
    5. 

  5. <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    6. 

  6. <meta http-equiv="X-UA-Compatible" content="IE=edge">
    7. 

  7. <link href="../static/theme.css" rel="stylesheet" type="text/css" />
    8. 

  8. <script src="../static/content.js" type="text/javascript"></script>
    9. 

  9. </head>
    10. 

  10. <body>
    11. 

  11. 

  12. <h1>Input</h1>
    13. 

  13. 

  14. <p>Waits for the user to type a string.</p>
    15. 

  15. 

  16. <pre class="Syntax">Input [, OutputVar, Options, EndKeys, MatchList]</pre>
    17. 

  17. <h3>Parameters</h3>
    18. 

  18. <dl>
    19. 

  19. 

  20.   <dt>OutputVar</dt>
    21. 

  21.   <dd><p>The name of the variable in which to store the text entered by the user (by default, artificial input is also captured).</p>
    22. 

  22.       <p>If this and the other parameters are omitted, any Input in progress in another <a href="../misc/Threads.htm">thread</a> is terminated and its <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to the word NewInput. By contrast, the <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 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.</p>
    23. 

  23.       <p><em>OutputVar</em> 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 <em>EndKeys</em> parameter below).</p>
    24. 

  24.       <p>Whitespace characters such as TAB (`t) are stored literally. ENTER is stored as linefeed (`n).</p></dd>
    25. 

  25. 

  26.   <dt>Options</dt>
    27. 

  27.   <dd><p><u>A string of zero or more of the following letters (in any order, with optional spaces in between):</u></p>
    28. 

  28.       <p><strong>B</strong>: 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).</p>
    29. 

  29.       <p><strong>C</strong>: Case sensitive. Normally, <em>MatchList</em> 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 &uuml;/&Uuml;).</p>
    30. 

  30.       <p><strong>I</strong>: Ignore input generated by any AutoHotkey script, such as the <a href="Send.htm#SendEvent">SendEvent</a> command. However, the <a href="Send.htm#SendInput">SendInput</a> and <a href="Send.htm#SendPlay">SendPlay</a> methods are always ignored, regardless of this setting.</p>      
    31. 

  31.       <p><strong>L</strong>: Length limit (e.g. <code>L5</code>). The maximum allowed length of the input. When the text reaches this length, the Input will be terminated and <a href="../misc/ErrorLevel.htm">ErrorLevel</a> will be set to the word Max unless the text matches one of the <em>MatchList</em> phrases, in which case <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to the word Match. If unspecified, the length limit is 16383, which is also the absolute maximum.</p>
    32. 

  32.       <p><strong>M</strong>: 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:</p>
    33. 

  33.       <pre>Transform, CtrlC, Chr, 3 <em>; Store the character for Ctrl-C in the CtrlC var.</em>
    34. 

  34. Input, OutputVar, L1 M
    35. 

  35. if OutputVar = %CtrlC%
    36. 

  36.     MsgBox, You pressed Control-C.
    37. 

  37. ExitApp</pre>
    38. 

  38.       <p>Note: The characters Ctrl-A through Ctrl-Z correspond to <a href="../Functions.htm#Chr">Chr(1)</a> through <a href="../Functions.htm#Chr">Chr(26)</a>. Also, the <strong>M</strong> option might cause some keyboard shortcuts such as Ctrl-LeftArrow to misbehave while an Input is in progress.</p>
    39. 

  39.       <p><strong>T</strong>: Timeout (e.g. <code>T3</code>). The number of seconds to wait before terminating the Input and setting <a href="../misc/ErrorLevel.htm">ErrorLevel</a> to the word Timeout. If the Input times out, <em>OutputVar</em> will be set to whatever text the user had time to enter. This value can be a floating point number such as 2.5.</p>
    40. 

  40.       <p id="vis"><strong>V</strong>: 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.</p>
    41. 

  41.       <p id="asterisk"><strong>*</strong>: Wildcard (find anywhere). Normally, what the user types must exactly match one of the <em>MatchList</em> phrases  for a match to occur. Use this option to find a match more often by searching the entire length of the input text.</p>
    42. 

  42.       <p id="E"><strong>E</strong> <span class="ver">[v1.1.20+]</span>: 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 <code>@</code> 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 <strong>C</strong> option is also used, the end character is case-sensitive.</p>
    43. 

  43.       </dd>
    44. 

  44. 

  45.   <dt>EndKeys</dt>
    46. 

  46.   <dd><p>A list of zero or more keys, any one of which terminates the Input when pressed (the <em>EndKey</em> itself is not written to <em>OutputVar</em>). When an Input is terminated this way, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to the word EndKey followed by a colon and the name of the <em>EndKey</em>. Examples: <code>EndKey:.</code>, <code>EndKey:Escape</code>.</p>
    47. 

  47.       <p>The <em>EndKey</em> list uses a format similar to the <a href="Send.htm">Send</a> command. For example, specifying <code>{Enter}.{Esc}</code> would cause either ENTER, period (.), or ESCAPE to terminate the Input. To use the braces themselves as end keys, specify <code>{{}</code> and/or <code>{}}</code>.</p>
    48. 

  48.       <p>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 <code>{LControl}{RControl}</code> rather than <code>{Control}</code>.</p>
    49. 

  49.       <p>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 ?!:@&amp;{} -- are supported in v1.0.14+. Other characters are supported with the <code>E</code> option described above, in v1.1.20+.</p>
    50. 

  50.       <p>An explicit virtual key code such as <code>{vkFF}</code> 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 <a href="../KeyList.htm#SpecialKeys">key list page</a>.</p>
    51. 

  51.     </dd>
    52. 

  52. 

  53.   <dt>MatchList</dt>
    54. 

  54.   <dd><p>A comma-separated list of key phrases, any of which will cause the Input to be terminated (in which case <a href="../misc/ErrorLevel.htm">ErrorLevel</a> 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 <a href="#asterisk">* option</a> is present). In addition, <strong>any spaces or tabs around the delimiting commas are significant</strong>, meaning that they are part of the match string. For example, if <em>MatchList</em> is &quot;ABC , XYZ &quot;, the user must type a space after ABC or before XYZ to cause a match.</p>
    55. 

  55.       <p>Two consecutive commas results in a single literal comma. For example, the following would produce a single literal comma at the end of string: &quot;string1,,,string2&quot;. Similarly, the following list contains only a single item with a literal comma inside it: &quot;single,,item&quot;.</p>
    56. 

  56.     <p>Because the items in <em>MatchList</em> 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, <em>MatchList</em> might consist of <code>%List1%,%List2%,%List3%</code> -- where each of the variables  contains a large sub-list of match phrases.</p>
    57. 

  57.     </dd>
    58. 

  58. 

  59. </dl>
    60. 

  60. 

  61. <h3>ErrorLevel</h3>
    62. 

  62. <p><span class="ver">[v1.1.04+]</span> This command is able to throw an exception if called with no parameters and there is no Input in progress. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
    63. 

  63. <table class="info">
    64. 

  64.   <tr>
    65. 

  65.     <td style="width:15%"><p>1 or 0</p></td>
    66. 

  66.     <td><p>Whenever the command is used without parameters, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 0 if it successfully terminates a prior input, or 1 if there is no Input in progress.</p></td>
    67. 

  67.   </tr>
    68. 

  68.   <tr>
    69. 

  69.     <td>NewInput</td>
    70. 

  70.     <td>The Input was interrupted by another <a href="../misc/Threads.htm">thread</a> that used the Input command.</td>
    71. 

  71.   </tr>
    72. 

  72.   <tr>
    73. 

  73.     <td>Max</td>
    74. 

  74.     <td>The Input reached the maximum allowed length and it does not match any of the items in <em>MatchList</em>.</td>
    75. 

  75.   </tr>
    76. 

  76.   <tr>
    77. 

  77.     <td>Timeout</td>
    78. 

  78.     <td>The Input timed out.</td>
    79. 

  79.   </tr>
    80. 

  80.   <tr>
    81. 

  81.     <td>Match</td>
    82. 

  82.     <td>The Input matches one of the items in <em>MatchList</em>.</td>
    83. 

  83.   </tr>
    84. 

  84.   <tr>
    85. 

  85.     <td>EndKey:<em>name</em></td>
    86. 

  86.     <td>
    87. 

  87.       <p>One of the <em>EndKeys</em> was pressed to terminate the Input. In this case, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> contains the word EndKey followed by a colon and the name of the terminating key without braces, e.g. &quot;EndKey:Enter&quot;, &quot;EndKey:Escape&quot;, etc.</p>
    88. 

  88.       <p>Note that <em>name</em> is the "normalized" name of the key regardless of how it was written in <em>EndKeys</em>. For example, {Esc} and {vk1B} both produce "ErrorLevel:Escape". <a href="../Functions.htm#GetKeyName">GetKeyName()</a> can be used to retrieve the normalized name.</p>
    89. 

  89.       <p>If the <a href="#E">E option</a> was used, <em>name</em> is the actual character which was typed (if applicable). Otherwise, the key name is determined according to the script's active keyboard layout.</p>
    90. 

  90.       <p>Prior to <span class="ver">[v1.1.20]</span>, 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.</p>
    91. 

  91.     </td>
    92. 

  92.   </tr>
    93. 

  93. </table>
    94. 

  94. <h3>Remarks</h3>
    95. 

  95. <p>If this command is used while an Input is  already in progress in another <a href="../misc/Threads.htm">thread</a>, that Input will be terminated and its <a href="../misc/ErrorLevel.htm">ErrorLevel</a> will be set to the word NewInput. After that (if parameters were given), the new Input will commence.</p>
    96. 

  96. <p>While an Input is in progress, new <a href="../misc/Threads.htm">threads</a> such as <a href="Menu.htm">custom menu items</a> and <a href="SetTimer.htm">timed subroutines</a> can still be created. Similarly, keyboard <a href="../Hotkeys.htm">hotkeys</a> are still in effect if the Input is <a href="#vis">visible</a>. If the Input is not visible, only <a href="_UseHook.htm">hook hotkeys</a> can be triggered.</p>
    97. 

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

  98. <p>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 <a href="#vis">visible</a>). However, in versions prior to 1.0.44.03, the script's own layout is used.</p>
    99. 

  99. <p>Although not as flexible, <a href="../Hotstrings.htm">hotstrings</a> are generally easier to use than the Input command.</p>
    100. 

  100. <h3>Related</h3>
    101. 

  101. <p><a href="KeyWait.htm">KeyWait</a>, <a href="../Hotstrings.htm">Hotstrings</a>, <a href="InputBox.htm">InputBox</a>, <a href="_InstallKeybdHook.htm">#InstallKeybdHook</a>, <a href="../misc/Threads.htm">Threads</a>, <a href="IfIn.htm">if var in/contains MatchList</a></p>
    102. 

  102. <h3>Examples</h3>
    103. 

  103. <pre class="NoIndent"><em>; Wait for the user to press any key.  Keys that produce no visible character -- such as
    104. 

  104. ; the modifier keys, function keys, and arrow keys -- are listed as end keys so that they
    105. 

  105. ; will be detected too.</em>
    106. 

  106. 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}</pre>
    107. 

  107. <p>&nbsp;</p>
    108. 

  108. <pre class="NoIndent"><em>; This is a working hotkey example.  Since the hotkey has the tilde (~)
    109. 

  109. ; prefix, its own keystroke will pass through to the active window.
    110. 

  110. ; Thus, if you type [btw (or one of the other match
    111. 

  111. ; phrases) in any editor, the script will automatically perform an
    112. 

  112. ; action of your choice (such as replacing the typed text):</em>
    113. 

  113. 

  114. ~[::
    115. 

  115. Input, UserInput, V T5 L4 C, {enter}.{esc}{tab}, btw,otoh,fl,ahk,ca
    116. 

  116. if (ErrorLevel = "Max")
    117. 

  117. {
    118. 

  118.     MsgBox, You entered &quot;%UserInput%&quot;, which is the maximum length of text.
    119. 

  119.     return
    120. 

  120. }
    121. 

  121. if (ErrorLevel = "Timeout")
    122. 

  122. {
    123. 

  123.     MsgBox, You entered &quot;%UserInput%&quot; at which time the input timed out.
    124. 

  124.     return
    125. 

  125. }
    126. 

  126. if (ErrorLevel = "NewInput")
    127. 

  127.     return
    128. 

  128. If InStr(ErrorLevel, "EndKey:")
    129. 

  129. {
    130. 

  130.     MsgBox, You entered &quot;%UserInput%&quot; and terminated the input with %ErrorLevel%.
    131. 

  131.     return
    132. 

  132. }
    133. 

  133. <em>; Otherwise, a match was found.</em>
    134. 

  134. if (UserInput = "btw")
    135. 

  135.     Send, {backspace 4}by the way
    136. 

  136. else if (UserInput = "otoh")
    137. 

  137.     Send, {backspace 5}on the other hand
    138. 

  138. else if (UserInput = "fl")
    139. 

  139.     Send, {backspace 3}Florida
    140. 

  140. else if (UserInput = "ca")
    141. 

  141.     Send, {backspace 3}California
    142. 

  142. else if (UserInput = "ahk")
    143. 

  143.     Run, https://autohotkey.com
    144. 

  144. return</pre>
    145. 

  145. 

  146. </body>
    147. 

  147. </html>
    148. 

  148.