Wyx dictionary

.FUNCTION....: Getk (Get Keypress) Function
.CATEGORY....: functions
.DISCUSSION..:
The GETK function waits for the user to press an acceptable key, then produces the key as its output. If the key pressed is a letter, then the letter is returned IN UPPER CASE. This feature is designed to support simple "pick a menu selection" processing in batch files.

The GETK function takes a /K "keymask" parameter that tells it which keys to accept. If the user presses an unacceptable key (i.e. one that is not in the keymask), the keypress is ignored.

If no /K parm is specified, the default keymask is:

ABCDEFGHIJKLMNOPQRSTUVWXYZx That is, the default keymask will accept letters and the ESCAPE key.

SPECIFYING THE KEYMASK

NOTE THAT THE VALUES SPECIFIED ON THE /K PARM ARE CASE-SENSITIVE.

The keymask may contain numbers, uppercase letters, and any of the other printable characters on the keyboard.

There is no way to tell Fdate to accept "special" keypresses such as function keys, ALT or CONTROL keys, arrow keys, etc.

If the keymask contains an uppercase letter (e.g. "A"), and the user presses the corresponding unshifted letter (e.g. "a"), then the keypress will be accepted and the uppercase letter will be returned.

The keymask may contain the following lowercase letters, which have special meanings:

x represents the ESCAPE key
e represents the ENTER (RETURN) key
z [a place-holder character]

Lowercase "z" will be ignored when Fdate decides which keypresses are acceptable. Its presence in the keymask will affect the positions of other characters in the keymask, and hence the ERRORLEVEL that Fdate returns when the user presses an acceptable key. (For the uses of "z", see "GetK Results also in ERRORLEVEL" and "Modifying the Keymask", below.)

All other lowercase letters are reserved for possible future use. In the current release of Fdate, they are treated like lowercase "z".

For example:

If a keymask of "/kXx" was specified, then if the user pressed the
(shifted or unshifted) "X" key, then uppercase "X" would be returned.

If he pressed the ESCAPE key, then lowercase "x" would be returned.

SPECIFYING HOW MANY SECONDS TO WAIT FOR A KEYPRESS

Starting with version 10, GETK takes a /W "seconds to wait" parameter that tells it how many seconds to wait before returning the first key in the /K "keymask" parameter. Valid values are in the range of 1..36000 (10 hours). Default value of /W is 36000 (10 hours).

GETK RESULTS ALSO IN ERRORLEVEL

When the GETK function returns a key, it sets the DOS errorlevel to a value corresponding to the position of that key in the keymask. For example, with keymask of "/kABx", if the user presses:

          "A": value returned will be "A", errorlevel will be 1
          "B": value returned will be "B", errorlevel will be 2
       ESCAPE: value returned will be "x", errorlevel will be 3

If the user presses CONTROL+BREAK, Fdate will abort and return errorlevel 255.

.EXAMPLE.....:

  @echo off
  cls
  echo Demonstration of Fdate's GETK (get keypress) function
  echo Press CONTROL+BREAK to end
  :top
  echo.
  Fdate /fGetK /P"You pressed: " /Q"Press a key: "  /K"12ABxe "
  if errorlevel 1  if not errorlevel 2  echo errorlevel : 1
  if errorlevel 2  if not errorlevel 3  echo errorlevel : 2
  if errorlevel 3  if not errorlevel 4  echo errorlevel : 3
  if errorlevel 4  if not errorlevel 5  echo errorlevel : 4
  if errorlevel 5  if not errorlevel 6  echo errorlevel : 5
  if errorlevel 6  if not errorlevel 7  echo errorlevel : 6
  if errorlevel 7  if not errorlevel 8  echo errorlevel : 7
  if errorlevel 255 echo ERRORLEVEL 255
  if errorlevel 255 goto endit
  goto top
  :endit

.DISCUSSION..:
Note that the keymask may contain blanks if the keymask is enclosed in quotes (as in this example batch file). But remember that Fdate eliminates redundant spaces when obtaining its parameter input, so you should never include more than one blank in your keymask.

Modifying the Keymask

It is often necessary to make program modifications during the life of a batch file. If you are using the GETK function and testing the errorlevel rather than the environment, then the insertion or deletion of characters into the existing keymask will change the errorlevels returned by the following characters in the keymask. This will force you to re-write the errorlevel tests, which may be a big job if the keymask is long.

Here are some tips on how to avoid this work:

When ADDING a character to the keymask, always add it at the END of the keymask.
When DELETING a character from the keymask, do not actually delete it. Instead, replace it by a lowercase "z".

Displaying a User Prompt With GETK

The /Q (user prompt) parameter is especially handy when used in conjunction with the GETK function. If the /Q prompt-string parameter is specified (as in the example batch file, above), then the prompt string is displayed, but a NEWLINE is not written to the screen before waiting for the user's keypress.

For a program that provides more sophisticated "get key" functions for batch files, I recommend Bob Stephan's shareware program GET, which is described elsewhere in this documentation.