Purpose:Get a single keystroke from the user and store it in an environment or array variable

 

Format:INKEY [/C /D /E"n" /K"keys" /P /M /Wait /X]  [prompt] %%varname

 

promptOptional text that is displayed as a prompt.
varnameThe variable that will hold the user's keystroke.
waitTime to wait for a keystroke, in seconds

 

/C

Clear buffer

/P

Password

/D

Digits only

/W

Wait

/K

valid keystrokes

/X

no carriage return

/M

Mouse buttons



 

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 batch file fragment 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.

 

INKEY works within the command line window. If you prefer to use a dialog for user input, see the MSGBOX and QUERYBOX commands.

 

Options:

 

/CClears the keyboard buffer before INKEY accepts keystrokes. If you use this option, INKEY will ignore any keystrokes which you type, either accidentally or intentionally, before it is ready to accept input.

 

/DOnly accept numbers from 0 to 9.

 

/K"keys"Specifies the permissible keystrokes. The list of valid keystrokes should be enclosed in double quotes. For alphabetic keys the validity test is not case sensitive. You can specify extended keys by enclosing their names in square brackets (within the quotes), for example:

 

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 will echo the keystroke if possible, beep, move the cursor back one character, and wait for another keystroke.

 

/MAccept mouse button clicks. This is enabled only if Windows' Quick Edit is disabled (alt-space -> Properties -> Options).

 

/PPrevents INKEY from echoing the character.

 

/WTime-out period, in seconds, to wait for a response. If no keystroke is entered by the end of the time-out period, INKEY returns with the variable unchanged. This allows you to continue the batch file if the user does not respond in a given period of time. You can specify /W0 to return immediately if there are no keys waiting in the keyboard buffer. If /W is specified, mouse buttons are ignored.

 

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

 

/XPrevents INKEY from displaying a carriage return and line feed after the user's entry.