Purpose: | Get a single keystroke from the user and store it in an environment or array variable |
Format: | INKEY [/= /C /D /K"keys" /P /M /T /Wn /X] [prompt] %%varname |
prompt | Optional text that is displayed as a prompt. |
varname | The variable that will hold the user's keystroke. |
wait | Time to wait for a keystroke, in seconds |
Clear buffer |
Password |
||
Digits only |
Countdown timer |
||
valid keystrokes |
Wait |
||
Mouse buttons |
no carriage return |
See also: INPUT.
Usage:
INKEY optionally displays a prompt, then it waits for a specified time (or indefinitely) for a keystroke, and places the keystroke into an environment or array variable. It is normally used in batch files and aliases to get a menu choice or other single-key input. Along with the INPUT command, INKEY allows great flexibility in reading input from within a batch file or alias.
If prompt is included in an INKEY command, it is displayed while INKEY waits for input.
The following command prompts for a character and stores it in the variable NUM:
inkey /D Enter a number from 1 to 9: %%num
INKEY reads standard input for the keystroke, so it will accept keystrokes from a redirected file or from KEYSTACK. You can supply a list of valid keystrokes with the /K option.
Numeric input may be entered in either decimal format (a sequence of 0-9 digits) or in hexadecimal format ("0x" followed by a sequence of 0-F hex digits).
A standard keystroke is stored directly in the environment variable. An extended keystroke (for example, a function key or a and cursor key) is stored as a string, consisting of a leading @, followed by its scan code as a decimal number, e.g., the F1 key is stored as @59. The Enter key is stored as an extended keystroke @28. See ASCII, Key Codes, and ANSI X3.64 Commands for scan codes.
When the /M option enables recognition of mouse buttons, (and /W is not specified), the variable is set to a single character with one of the codes below:
button |
code |
left |
240 |
middle |
498 |
right |
497 |
You can get the screen position of the last mouse click with the _xmouse and _ymouse internal variables.
To test for a non-printing value returned by INKEY use the @ASCII function to get the numeric value of the key, or convert the expected value of the code to a code using @CHAR. For example, to test for Esc, which has an ASCII value of 27 or a left mouse button:
inkey Enter a key: %%key
if "%@ascii[%key]" == "27" echo Esc pressed
if %key EQ %@char[240] echo Left mouse button clicked
If you press Ctrl-C or Ctrl-Break while INKEY is waiting for a key, execution of an alias will be terminated, and execution of a batch file will be suspended while you are asked whether to cancel the batch job. A batch file can handle Ctrl-C and Ctrl-Break with the ON BREAK command.
If you don't enter any arguments, INKEY will display its command dialog.
INKEY works within the command line window. If you prefer to use a dialog for user input, see the MSGBOX and QUERYBOX commands.
Options:
/= | Display the INKEY command dialog to help you set the command line options. The /= option can be anywhere on the line; additional options will set the appropriate fields in the command dialog. |
inkey /k"ab[Ctrl-F9]" Enter A, B, Ctrl-F9 %%var
See Keys and Key Names for a complete listing of the key names you can use within the square brackets, and a description of the key name format.
If an invalid keystroke is entered, TCC-RT will echo the keystroke if possible, beep, move the cursor back one character, and wait for another keystroke.
/M | Accept mouse button clicks. This is enabled only if Windows' Quick Edit is disabled (alt-space -> Properties -> Options). |
For example, the following batch file fragment waits up to 10 seconds for a character, then tests to see if a "Y" was entered:
set netmon=N
inkey /K"YN" /w10 Network monitor (Y/N)? %%netmon
iff "%netmon" == "Y" then
rem Commands to load the monitor program
endiff