Getkey

NAME
    Getkey: Get keystroke input

VERSION
    7; 28Jan2002

AUTHOR
    Bill Stewart (bstewart@iname.com)

SYNOPSIS
    getkey [-k keys] [-d key] [-t key,n] [-p prompt] [-n] [-q] [-s]

AVAILABILITY
    DOS version (getkeyd.exe)
    Win32 console mode version (getkey.exe)

    Getkeyd.exe is a real-mode MS-DOS version that should work with any
    version of DOS, Windows 9x, etc. Getkey.exe is a Win32 console-mode
    version for Windows 9x/NT/2000 (Intel only).

    You can use the DOS version in NT/2000 also, but since it runs in a DOS
    emulator, it runs much more slowly (the screen isn't updated as quickly
    or smoothly).

    Due to the fact that Win32 console programs are very flaky on the
    Windows 9x platform (Windows 95/98/Me), it's better to use the DOS
    version there.

    DOS and Windows 9x come with a choice command, and the Windows NT/2000
    resource kit also comes with a version for Windows NT/2000. This is
    somewhat confusing since both file are named choice.exe. The choice
    utility is not as flexible as getkey. Also, getkey doesn't beep every
    time an invalid keystroke is pressed, which this author considers
    annoying.

    The Win32 version of getkey has an additional advantage over the
    NT/2000 choice utility: It gracefully handles Ctrl+C/Ctrl+Break. Getkey
    will return an exit code of 255 when Ctrl+C is pressed, whereas the
    NT/2000 choice utility returns an undefined exit code. Getkey ignores
    Ctrl+Break altogether.

DESCRIPTION
    Getkey is a utility intended for use in batch files (scripts). It's
    purpose is to allow a single character of input and return it as an
    exit code (ERRORLEVEL).

PARAMETERS
    Command-line parameters that start with a forward slash (/) or a hyphen
    (-) character are "switches" that modify the program's behavior, and
    may be specified in upper or lowercase. Switches that don't require an
    additional argument may be combined (e.g. -a -b is the same as -ab).

    If a command-line parameter's argument needs to contain one or more
    spaces or tabs, the argument needs to be enclosed in either single (')
    or double (") quotation marks. The general rule is that if a
    parameter's argument needs embedded spaces, separate the parameter and
    it's argument with a space and enclose the argument in quotes.

    -h  Displays an on-screen synopsis.

    -k  Specifies the list of valid keystrokes. The default is YN (e.g., Y
        and N are the only keys that getkey will let you press).

    -d  Specifies a "default" keystroke; that is, if you press Enter,
        getkey assumes you pressed the default key.

    -t  Specifies a keystroke and a timeout period in seconds. If no keys
        are pressed within the specified number of seconds, getkey will
        automatically choose the specified keystroke.

    -p  Specifies a prompt that should be displayed. If the prompt should
        contain one or more spaces or tabs, enclose it in quotation marks.
        If -n is not specified, a list of valid keystrokes in square
        brackets is displayed following this prompt.

    -n  Specifies that getkey should not display the list of valid
        keystrokes as part of its prompt. Normally, getkey will display a
        prompt in the form of "[A,B,C]" (where A, B, C are the choices).

    -q  Specifies that getkey should not display the keystroke that was
        pressed, or a carriage return.

    -s  Specifies that getkey should be case-sensitive; that is, Y is
        different from y.

    The string "--" (without the quotes) indicates the end of switches on
    the command line. This is useful if the prompt contains a string that
    might be confused with a switch.

EXIT STATUS
    Getkey returns an exit code that corresponds to the position of the key
    pressed in the key list; e.g. if the key list is "ABC" and the letter B
    is pressed, the exit code will be 2. A batch file can use an "IF
    ERRORLEVEL" command to check getkey's exit code.

    If Ctrl+C is pressed, getkey will return an exit code of 255.

EXAMPLES
    1.  getkey -p "Are you sure?"

        Displays the following prompt, and waits for a keystroke:

        Are you sure? [Y,N]

    2.  getkey -k yna -d n -n -p "Rename this file (yes,NO,all)? "

        Displays the following prompt:

        Rename this file (yes,NO,all)?

        Getkey will return ERRORLEVEL 2 if N or Enter is pressed.

    3.  getkey -k 1 -d 1 -n -q -p "Press Enter to continue..."

        This is a simple way to force the user to press the Enter key. It
        defines the number 1 as the only acceptable keystroke, and sets it
        as the default key.

    4.  getkey -k abc -t c,30

        This will cause getkey to wait 30 seconds for a keystroke. If no
        keys are pressed within 30 seconds, getkey chooses the letter C
        automatically.

    See TESTKEY.BAT for a longer example.

NOTES
    The DOS version of getkey (getkeyd.exe) treats the Ctrl+Break keystroke
    the same as Ctrl+C; the Win32 version (getkey.exe) ignores the
    Ctrl+Break keystroke. This is a function of how the keyboard is handled
    in the different environments.

VERSION HISTORY
    Versions are numbered consecutively.

    7   28Jan2002

        No code changes.

    6   3Jul2001

        The Win32 version is compiled with Free Pascal 1.0.4 and now
        contains embedded version information and an icon. Both versions
        (DOS and Win32) are compressed with UPX 1.20.

    5   17Jan2001

        Changed -c parameter back to -s, for compatibility with choice.

    4   13Dec2000

        Recompiled the Win32 version with version 1.0.2 of Free Pascal,
        which fixed a minor keystroke input bug.

    3   20Nov2000

        *  Added the -t parameter.
        *  Command-line parameter checking is stricter.
        *  The case-sensitivity parameter -s was changed to -c.
        *  Getkey now empties the keyboard buffer before retrieving any
           keystrokes.

    2   06Nov2000

        The -p parameter is now required before the prompt string. The
        change was made because the "%0\..\" batch file syntax in Windows
        2000 (see Microsoft Knowledge Base article Q121387 for details)
        places quotes around the %0. The program then assumed that this was
        the prompt and ignored the later prompt on the command line. By
        requiring a -p to prefix the prompt, the program parses the command
        line correctly.

    1   04Oct2000

        Initial release.

TECHNICAL INFORMATION
    Getkey was written in Pascal. The DOS version is compiled with Turbo
    Pascal 7.0, and the Win32 version is compiled with Free Pascal (FPC).
    FPC is a free, Turbo Pascal/Delphi-compatible multi-platform 32-bit
    Pascal compiler that can compile executables for several platforms.
    Visit http://www.freepascal.org/ for more information.
